Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
VN_FULLPATH(9)		    Kernel Developer's Manual		  VN_FULLPATH(9)

NAME
     vn_fullpath  --  convert  a  vnode  reference  to	a full pathname, given a
     process context

SYNOPSIS
     #include <sys/param.h>
     #include <sys/vnode.h>

     int
     vn_fullpath(struct vnode *vp, char **retbuf, char **freebuf);

     int
     vn_fullpath_jail(struct vnode *vp, char **retbuf, char **freebuf);

     int
     vn_fullpath_global(struct vnode *vp, char **retbuf, char **freebuf);

     int
     vn_fullpath_hardlink(struct vnode *vp, struct vnode *dvp,
	 const char *hrdl_name, size_t hrdl_name_length, char **retbuf,
	 char **freebuf, size_t *buflen);

DESCRIPTION
     The vn_fullpath(), vn_fullpath_jail(),  vn_fullpath_global()  and	vn_full-
     path_hardlink()  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 vn_fullpath_hardlink() which be-
     haves like vn_fullpath() in this respect and is described at the end.

     The 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  di-
     rectory, or some descendant directory of such established by some chroot(2)
     call.   The  vn_fullpath_jail()  function	returns  a  path relative to the
     passed thread's process' current  jail's  root,  ignoring	intervening  ch-
     root(2)  calls  possibly  made  inside that jail.	The vn_fullpath_global()
     function returns the full path from the  system  root,  ignoring  all  jail
     roots and chroot(2) calls.

     Paths  that  the  kernel  intends	to communicate to the passed user thread
     should exclusively be  obtained  via  vn_fullpath().   Paths  obtained  via
     vn_fullpath_jail()  or  vn_fullpath_global()  are	only useful for specific
     kernel checks or auditing purposes.

     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).   How-
     ever,  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 re-
     sults of this function should anticipate (and properly handle) failure.

     These functions take the following arguments:

     vp       The vnode to search for.	No need to be locked by the caller.

     retbuf   Pointer to a char * that may be set (on success)	to  point  at  a
	      newly allocated buffer containing the resulting pathname.

     freebuf  Pointer  to  a  char  * that may be set (on success) to point at a
	      buffer to be freed, when the caller is done with retbuf.

     Typical  consumers  will  declare	two  character	pointers:  fullpath  and
     freepath;	they will set freepath to NULL, and fullpath to a name to use in
     the event that the call to vn_fullpath() fails.  After done with the  value
     of  fullpath, the caller will check if freepath is non-NULL, and if so, in-
     voke free(9) with a pool type of M_TEMP.

     The vn_fullpath_hardlink() function is a convenience wrapper which automat-
     ically appends  the  hardlink  name  passed  via  arguments  hrdl_name  and
     hrdl_name_length to the result of calling vn_fullpath() on the vnode's par-
     ent  directory.   It  requires the results of a prior call to namei(9) with
     flag WANTPARENT to be passed in the vp and dvp arguments.	Argument  buflen
     must  point  to  a valid storage containing the size of the desired buffer,
     which will be reduced to MAXPATHLEN if in excess of it.

RETURN VALUES
     If the vnode is successfully converted to a pathname, 0 is returned; other-
     wise, an error number is returned.

SEE ALSO
     free(9)

AUTHORS
     This  manual  page  was  initially  written   by	Robert	 Watson   <rwat-
     son@FreeBSD.org>  to describe the vn_fullpath() function.	The descriptions
     of  the  other  related   functions   were   added   by   Olivier	 Certner
     <olce@FreeBSD.org>.

FreeBSD ports 15.quarterly     September 29, 2025		  VN_FULLPATH(9)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=vn_fullpath&sektion=9&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>

home | help