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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
.\"-
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 2003 Robert N. M. Watson.
.\" All rights reserved.
.\" Copyright (c) 2025 The FreeBSD Foundation
.\"
.\" Portions of this documentation were written by Olivier Certner
.\" <olce@FreeBSD.org> at Kumacom SARL under sponsorship from the FreeBSD
.\" Foundation.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice(s), this list of conditions and the following disclaimer as
.\" the first lines of this file unmodified other than the possible
.\" addition of one or more copyright notices.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice(s), this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
.\" DAMAGE.
.\"
.Dd September 29, 2025
.Dt VN_FULLPATH 9
.Os
.Sh NAME
.Nm vn_fullpath
.Nd "convert a vnode reference to a full pathname, given a process context"
.Sh SYNOPSIS
.In sys/param.h
.In sys/vnode.h
.Ft int
.Fn vn_fullpath "struct vnode *vp" "char **retbuf" "char **freebuf"
.Ft int
.Fn vn_fullpath_jail "struct vnode *vp" "char **retbuf" "char **freebuf"
.Ft int
.Fn vn_fullpath_global "struct vnode *vp" "char **retbuf" "char **freebuf"
.Ft int
.Fo vn_fullpath_hardlink
.Fa "struct vnode *vp" "struct vnode *dvp"
.Fa "const char *hrdl_name" "size_t hrdl_name_length"
.Fa "char **retbuf" "char **freebuf" "size_t *buflen"
.Fc
.Sh DESCRIPTION
The
.Fn vn_fullpath ,
.Fn vn_fullpath_jail ,
.Fn vn_fullpath_global
and
.Fn vn_fullpath_hardlink
functions make a
.Dq 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
.Fn vn_fullpath_hardlink
which behaves like
.Fn vn_fullpath
in this respect and is described at the end.
.Pp
The
.Fn vn_fullpath
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
.Xr chroot 2
call.
The
.Fn vn_fullpath_jail
function returns a path relative to the passed thread's process' current jail's
root, ignoring intervening
.Xr chroot 2
calls possibly made inside that jail.
The
.Fn vn_fullpath_global
function returns the full path from the system root, ignoring all jail roots and
.Xr chroot 2
calls.
.Pp
Paths that the kernel intends to communicate to the passed user thread should
exclusively be obtained via
.Fn vn_fullpath .
Paths obtained via
.Fn vn_fullpath_jail
or
.Fn vn_fullpath_global
are only useful for specific kernel checks or auditing purposes.
.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.
.Pp
These functions take the following arguments:
.Bl -tag -width ".Fa freebuf"
.It Fa vp
The vnode to search for.
No need to be locked by the caller.
.It Fa retbuf
Pointer to a
.Vt "char *"
that may be set (on success) to point at a newly allocated buffer containing the
resulting pathname.
.It Fa freebuf
Pointer to a
.Vt "char *"
that may be set (on success) to point at a buffer to be freed, when the caller
is done with
.Fa retbuf .
.El
.Pp
Typical consumers will declare two character pointers:
.Va fullpath
and
.Va freepath ;
they will set
.Va freepath
to
.Dv NULL ,
and
.Va fullpath
to a name to use
in the event that the call to
.Fn vn_fullpath
fails.
After done with the value of
.Va fullpath ,
the caller will check if
.Va freepath
is
.Pf non- Dv NULL ,
and if so, invoke
.Xr free 9
with a pool type of
.Dv M_TEMP .
.Pp
The
.Fn vn_fullpath_hardlink
function is a convenience wrapper which automatically appends the hardlink name
passed via arguments
.Fa hrdl_name
and
.Fa hrdl_name_length
to the result of calling
.Fn vn_fullpath
on the vnode's parent directory.
It requires the results of a prior call to
.Xr namei 9
with flag
.Dv WANTPARENT
to be passed in the
.Fa vp
and
.Fa dvp
arguments.
Argument
.Fa buflen
must point to a valid storage containing the size of the desired buffer, which
will be reduced to
.Dv MAXPATHLEN
if in excess of it.
.Sh RETURN VALUES
If the vnode is successfully converted to a pathname, 0 is returned;
otherwise, an error number is returned.
.Sh SEE ALSO
.Xr free 9
.Sh AUTHORS
.An -nosplit
This manual page was initially written by
.An Robert Watson Aq Mt rwatson@FreeBSD.org
to describe the
.Fn vn_fullpath
function.
The descriptions of the other related functions were added by
.An Olivier Certner Aq Mt olce@FreeBSD.org .
|
