1 files changed, 98 insertions, 22 deletions
diff --git a/share/man/man9/vn_fullpath.9 b/share/man/man9/vn_fullpath.9
index 116f519ec8aa..9815abc3c86c 100644
--- a/share/man/man9/vn_fullpath.9
+++ b/share/man/man9/vn_fullpath.9
@@ -1,6 +1,13 @@
+.\"-
+.\" 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
@@ -25,7 +32,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
 .\" DAMAGE.
 .\"
-.Dd June 15, 2021
+.Dd September 29, 2025
 .Dt VN_FULLPATH 9
 .Os
 .Sh NAME
@@ -35,23 +42,64 @@
 .In sys/param.h
 .In sys/vnode.h
 .Ft int
-.Fo vn_fullpath
-.Fa "struct vnode *vp" "char **retbuf" "char **freebuf"
+.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
-function makes a
-.Dq "best effort"
-attempt to generate a string pathname for
-the passed vnode; the resulting path, if any, will be relative to
-the root directory of the process associated with the passed thread pointer.
+in this respect and is described at the end.
+.Pp
 The
 .Fn vn_fullpath
-function
-is implemented by inspecting the VFS name cache, and attempting to
-reconstruct a path from the process root to the object.
+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
@@ -64,7 +112,7 @@ 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
-Its arguments are:
+These functions take the following arguments:
 .Bl -tag -width ".Fa freebuf"
 .It Fa vp
 The vnode to search for.
@@ -72,17 +120,13 @@ No need to be locked by the caller.
 .It Fa retbuf
 Pointer to a
 .Vt "char *"
-that
-.Fn vn_fullpath
-may (on success) point at a newly
-allocated buffer containing the resulting pathname.
+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
-.Fn vn_fullpath
-may (on success) point at a buffer
-to be freed, when the caller is done with
+that may be set (on success) to point at a buffer to be freed, when the caller
+is done with
 .Fa retbuf .
 .El
 .Pp
@@ -110,11 +154,43 @@ 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
-This manual page was written by
-.An Robert Watson Aq Mt rwatson@FreeBSD.org .
+.An -nosplit
+This manual page was initally 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 .