1.\"- 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2003 Robert N. M. Watson. 5.\" All rights reserved. 6.\" Copyright (c) 2025 The FreeBSD Foundation 7.\" 8.\" Portions of this documentation were written by Olivier Certner 9.\" <olce@FreeBSD.org> at Kumacom SARL under sponsorship from the FreeBSD 10.\" Foundation. 11.\" 12.\" Redistribution and use in source and binary forms, with or without 13.\" modification, are permitted provided that the following conditions 14.\" are met: 15.\" 1. Redistributions of source code must retain the above copyright 16.\" notice(s), this list of conditions and the following disclaimer as 17.\" the first lines of this file unmodified other than the possible 18.\" addition of one or more copyright notices. 19.\" 2. Redistributions in binary form must reproduce the above copyright 20.\" notice(s), this list of conditions and the following disclaimer in the 21.\" documentation and/or other materials provided with the distribution. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 24.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 25.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 26.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 27.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 28.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 29.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 30.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 33.\" DAMAGE. 34.\" 35.Dd September 29, 2025 36.Dt VN_FULLPATH 9 37.Os 38.Sh NAME 39.Nm vn_fullpath 40.Nd "convert a vnode reference to a full pathname, given a process context" 41.Sh SYNOPSIS 42.In sys/param.h 43.In sys/vnode.h 44.Ft int 45.Fn vn_fullpath "struct vnode *vp" "char **retbuf" "char **freebuf" 46.Ft int 47.Fn vn_fullpath_jail "struct vnode *vp" "char **retbuf" "char **freebuf" 48.Ft int 49.Fn vn_fullpath_global "struct vnode *vp" "char **retbuf" "char **freebuf" 50.Ft int 51.Fo vn_fullpath_hardlink 52.Fa "struct vnode *vp" "struct vnode *dvp" 53.Fa "const char *hrdl_name" "size_t hrdl_name_length" 54.Fa "char **retbuf" "char **freebuf" "size_t *buflen" 55.Fc 56.Sh DESCRIPTION 57The 58.Fn vn_fullpath , 59.Fn vn_fullpath_jail , 60.Fn vn_fullpath_global 61and 62.Fn vn_fullpath_hardlink 63functions make a 64.Dq best effort 65attempt at generating a string pathname for the passed vnode. 66They differ in which directory the returned path is relative to, except for 67.Fn vn_fullpath_hardlink 68which behaves like 69.Fn vn_fullpath 70in this respect and is described at the end. 71.Pp 72The 73.Fn vn_fullpath 74function returns a path relative to the root directory of the process associated 75with the passed thread pointer. 76That root directory is either the system's or the thread's process' containing 77jail's root directory, or some descendant directory of such established by some 78.Xr chroot 2 79call. 80The 81.Fn vn_fullpath_jail 82function returns a path relative to the passed thread's process' current jail's 83root, ignoring intervening 84.Xr chroot 2 85calls possibly made inside that jail. 86The 87.Fn vn_fullpath_global 88function returns the full path from the system root, ignoring all jail roots and 89.Xr chroot 2 90calls. 91.Pp 92Paths that the kernel intends to communicate to the passed user thread should 93exclusively be obtained via 94.Fn vn_fullpath . 95Paths obtained via 96.Fn vn_fullpath_jail 97or 98.Fn vn_fullpath_global 99are only useful for specific kernel checks or auditing purposes. 100.Pp 101All these functions are implemented by inspecting the VFS name cache, and 102attempting to reconstruct a path from the process root to the object. 103This process is necessarily unreliable for several reasons: intermediate 104entries in the path may not be found in the cache; files may have more 105than one name (hard links), not all file systems use the name cache 106(specifically, most synthetic file systems do not); a single name may 107be used for more than one file (in the context of file systems covering 108other file systems); a file may have no name (if deleted but still 109open or referenced). 110However, the resulting string may still be more useable to a user than 111a vnode pointer value, or a device number and inode number. 112Code consuming the results of this function should anticipate (and 113properly handle) failure. 114.Pp 115These functions take the following arguments: 116.Bl -tag -width ".Fa freebuf" 117.It Fa vp 118The vnode to search for. 119No need to be locked by the caller. 120.It Fa retbuf 121Pointer to a 122.Vt "char *" 123that may be set (on success) to point at a newly allocated buffer containing the 124resulting pathname. 125.It Fa freebuf 126Pointer to a 127.Vt "char *" 128that may be set (on success) to point at a buffer to be freed, when the caller 129is done with 130.Fa retbuf . 131.El 132.Pp 133Typical consumers will declare two character pointers: 134.Va fullpath 135and 136.Va freepath ; 137they will set 138.Va freepath 139to 140.Dv NULL , 141and 142.Va fullpath 143to a name to use 144in the event that the call to 145.Fn vn_fullpath 146fails. 147After done with the value of 148.Va fullpath , 149the caller will check if 150.Va freepath 151is 152.Pf non- Dv NULL , 153and if so, invoke 154.Xr free 9 155with a pool type of 156.Dv M_TEMP . 157.Pp 158The 159.Fn vn_fullpath_hardlink 160function is a convenience wrapper which automatically appends the hardlink name 161passed via arguments 162.Fa hrdl_name 163and 164.Fa hrdl_name_length 165to the result of calling 166.Fn vn_fullpath 167on the vnode's parent directory. 168It requires the results of a prior call to 169.Xr namei 9 170with flag 171.Dv WANTPARENT 172to be passed in the 173.Fa vp 174and 175.Fa dvp 176arguments. 177Argument 178.Fa buflen 179must point to a valid storage containing the size of the desired buffer, which 180will be reduced to 181.Dv MAXPATHLEN 182if in excess of it. 183.Sh RETURN VALUES 184If the vnode is successfully converted to a pathname, 0 is returned; 185otherwise, an error number is returned. 186.Sh SEE ALSO 187.Xr free 9 188.Sh AUTHORS 189.An -nosplit 190This manual page was initally written by 191.An Robert Watson Aq Mt rwatson@FreeBSD.org 192to describe the 193.Fn vn_fullpath 194function. 195The descriptions of the other related functions were added by 196.An Olivier Certner Aq Mt olce@FreeBSD.org . 197