1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
<table class="head">
<tr>
<td class="head-ltitle">VN_FULLPATH(9)</td>
<td class="head-vol">Kernel Developer's Manual</td>
<td class="head-rtitle">VN_FULLPATH(9)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">vn_fullpath</code> —
<span class="Nd">convert a vnode reference to a full pathname, given a
process context</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">sys/param.h</a>></code>
<br/>
<code class="In">#include <<a class="In">sys/vnode.h</a>></code></p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">vn_fullpath</code>(<var class="Fa" style="white-space: nowrap;">struct
vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">char
**retbuf</var>, <var class="Fa" style="white-space: nowrap;">char
**freebuf</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">vn_fullpath_jail</code>(<var class="Fa" style="white-space: nowrap;">struct
vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">char
**retbuf</var>, <var class="Fa" style="white-space: nowrap;">char
**freebuf</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">vn_fullpath_global</code>(<var class="Fa" style="white-space: nowrap;">struct
vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">char
**retbuf</var>, <var class="Fa" style="white-space: nowrap;">char
**freebuf</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">vn_fullpath_hardlink</code>(<var class="Fa">struct vnode
*vp</var>, <var class="Fa">struct vnode *dvp</var>, <var class="Fa">const
char *hrdl_name</var>, <var class="Fa">size_t hrdl_name_length</var>,
<var class="Fa">char **retbuf</var>, <var class="Fa">char **freebuf</var>,
<var class="Fa">size_t *buflen</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The
<a class="permalink" href="#vn_fullpath"><code class="Fn" id="vn_fullpath">vn_fullpath</code></a>(),
<a class="permalink" href="#vn_fullpath_jail"><code class="Fn" id="vn_fullpath_jail">vn_fullpath_jail</code></a>(),
<a class="permalink" href="#vn_fullpath_global"><code class="Fn" id="vn_fullpath_global">vn_fullpath_global</code></a>()
and <code class="Fn">vn_fullpath_hardlink</code>() functions make a
“best effort” attempt at generating a string pathname for the
passed vnode. They differ in which directory the returned path is relative
to, except for <code class="Fn">vn_fullpath_hardlink</code>() which behaves
like <code class="Fn">vn_fullpath</code>() in this respect and is described
at the end.</p>
<p class="Pp" id="vn_fullpath~2">The
<a class="permalink" href="#vn_fullpath~2"><code class="Fn">vn_fullpath</code></a>()
function returns a path relative to the root directory of the process
associated with the passed thread pointer. That root directory is either the
system's or the thread's process' containing jail's root directory, or some
descendant directory of such established by some <a class="Xr">chroot(2)</a>
call. The
<a class="permalink" href="#vn_fullpath_jail~2"><code class="Fn" id="vn_fullpath_jail~2">vn_fullpath_jail</code></a>()
function returns a path relative to the passed thread's process' current
jail's root, ignoring intervening <a class="Xr">chroot(2)</a> calls possibly
made inside that jail. The
<a class="permalink" href="#vn_fullpath_global~2"><code class="Fn" id="vn_fullpath_global~2">vn_fullpath_global</code></a>()
function returns the full path from the system root, ignoring all jail roots
and <a class="Xr">chroot(2)</a> calls.</p>
<p class="Pp" id="vn_fullpath~3">Paths that the kernel intends to communicate to
the passed user thread should exclusively be obtained via
<a class="permalink" href="#vn_fullpath~3"><code class="Fn">vn_fullpath</code></a>().
Paths obtained via
<a class="permalink" href="#vn_fullpath_jail~3"><code class="Fn" id="vn_fullpath_jail~3">vn_fullpath_jail</code></a>()
or
<a class="permalink" href="#vn_fullpath_global~3"><code class="Fn" id="vn_fullpath_global~3">vn_fullpath_global</code></a>()
are only useful for specific kernel checks or auditing purposes.</p>
<p class="Pp">All these functions are implemented by inspecting the VFS name
cache, and attempting to reconstruct a path from the process root to the
object. This process is necessarily unreliable for several reasons:
intermediate entries in the path may not be found in the cache; files may
have more than one name (hard links), not all file systems use the name
cache (specifically, most synthetic file systems do not); a single name may
be used for more than one file (in the context of file systems covering
other file systems); a file may have no name (if deleted but still open or
referenced). However, the resulting string may still be more usable to a
user than a vnode pointer value, or a device number and inode number. Code
consuming the results of this function should anticipate (and properly
handle) failure.</p>
<p class="Pp">These functions take the following arguments:</p>
<dl class="Bl-tag">
<dt><var class="Fa">vp</var></dt>
<dd>The vnode to search for. No need to be locked by the caller.</dd>
<dt><var class="Fa">retbuf</var></dt>
<dd>Pointer to a <var class="Vt">char *</var> that may be set (on success) to
point at a newly allocated buffer containing the resulting pathname.</dd>
<dt><var class="Fa">freebuf</var></dt>
<dd>Pointer to a <var class="Vt">char *</var> that may be set (on success) to
point at a buffer to be freed, when the caller is done with
<var class="Fa">retbuf</var>.</dd>
</dl>
<p class="Pp" id="vn_fullpath~4">Typical consumers will declare two character
pointers: <var class="Va">fullpath</var> and <var class="Va">freepath</var>;
they will set <var class="Va">freepath</var> to
<code class="Dv">NULL</code>, and <var class="Va">fullpath</var> to a name
to use in the event that the call to
<a class="permalink" href="#vn_fullpath~4"><code class="Fn">vn_fullpath</code></a>()
fails. After done with the value of <var class="Va">fullpath</var>, the
caller will check if <var class="Va">freepath</var> is
non-<code class="Dv">NULL</code>, and if so, invoke
<a class="Xr">free(9)</a> with a pool type of
<code class="Dv">M_TEMP</code>.</p>
<p class="Pp" id="vn_fullpath_hardlink">The
<a class="permalink" href="#vn_fullpath_hardlink"><code class="Fn">vn_fullpath_hardlink</code></a>()
function is a convenience wrapper which automatically appends the hardlink
name passed via arguments <var class="Fa">hrdl_name</var> and
<var class="Fa">hrdl_name_length</var> to the result of calling
<code class="Fn">vn_fullpath</code>() on the vnode's parent directory. It
requires the results of a prior call to <a class="Xr">namei(9)</a> with flag
<code class="Dv">WANTPARENT</code> to be passed in the
<var class="Fa">vp</var> and <var class="Fa">dvp</var> arguments. Argument
<var class="Fa">buflen</var> must point to a valid storage containing the
size of the desired buffer, which will be reduced to
<code class="Dv">MAXPATHLEN</code> if in excess of it.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp">If the vnode is successfully converted to a pathname, 0 is
returned; otherwise, an error number is returned.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">free(9)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">This manual page was initially written by <span class="An">Robert
Watson</span>
<<a class="Mt" href="mailto:rwatson@FreeBSD.org">rwatson@FreeBSD.org</a>>
to describe the <code class="Fn">vn_fullpath</code>() function. The
descriptions of the other related functions were added by
<span class="An">Olivier Certner</span>
<<a class="Mt" href="mailto:olce@FreeBSD.org">olce@FreeBSD.org</a>>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">September 29, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
