1.\" 2.\" Copyright (c) 2003 Robert N. M. Watson. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice(s), this list of conditions and the following disclaimer as 10.\" the first lines of this file unmodified other than the possible 11.\" addition of one or more copyright notices. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice(s), this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 18.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 20.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 21.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 22.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 23.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 26.\" DAMAGE. 27.\" 28.Dd June 15, 2021 29.Dt VN_FULLPATH 9 30.Os 31.Sh NAME 32.Nm vn_fullpath 33.Nd "convert a vnode reference to a full pathname, given a process context" 34.Sh SYNOPSIS 35.In sys/param.h 36.In sys/vnode.h 37.Ft int 38.Fo vn_fullpath 39.Fa "struct vnode *vp" "char **retbuf" "char **freebuf" 40.Fc 41.Sh DESCRIPTION 42The 43.Fn vn_fullpath 44function makes a 45.Dq "best effort" 46attempt to generate a string pathname for 47the passed vnode; the resulting path, if any, will be relative to 48the root directory of the process associated with the passed thread pointer. 49The 50.Fn vn_fullpath 51function 52is implemented by inspecting the VFS name cache, and attempting to 53reconstruct a path from the process root to the object. 54.Pp 55This process is necessarily unreliable for several reasons: intermediate 56entries in the path may not be found in the cache; files may have more 57than one name (hard links), not all file systems use the name cache 58(specifically, most synthetic file systems do not); a single name may 59be used for more than one file (in the context of file systems covering 60other file systems); a file may have no name (if deleted but still 61open or referenced). 62However, the resulting string may still be more useable to a user than 63a vnode pointer value, or a device number and inode number. 64Code consuming the results of this function should anticipate (and 65properly handle) failure. 66.Pp 67Its arguments are: 68.Bl -tag -width ".Fa freebuf" 69.It Fa vp 70The vnode to search for. 71No need to be locked by the caller. 72.It Fa retbuf 73Pointer to a 74.Vt "char *" 75that 76.Fn vn_fullpath 77may (on success) point at a newly 78allocated buffer containing the resulting pathname. 79.It Fa freebuf 80Pointer to a 81.Vt "char *" 82that 83.Fn vn_fullpath 84may (on success) point at a buffer 85to be freed, when the caller is done with 86.Fa retbuf . 87.El 88.Pp 89Typical consumers will declare two character pointers: 90.Va fullpath 91and 92.Va freepath ; 93they will set 94.Va freepath 95to 96.Dv NULL , 97and 98.Va fullpath 99to a name to use 100in the event that the call to 101.Fn vn_fullpath 102fails. 103After done with the value of 104.Va fullpath , 105the caller will check if 106.Va freepath 107is 108.Pf non- Dv NULL , 109and if so, invoke 110.Xr free 9 111with a pool type of 112.Dv M_TEMP . 113.Sh RETURN VALUES 114If the vnode is successfully converted to a pathname, 0 is returned; 115otherwise, an error number is returned. 116.Sh SEE ALSO 117.Xr free 9 118.Sh AUTHORS 119This manual page was written by 120.An Robert Watson Aq Mt rwatson@FreeBSD.org . 121