1.\" 2.\" Copyright (c) 2004 Hiten Pandya <hmp@backplane.com>. All rights reserved. 3.\" Copyright (c) 2003 Robert N. M. Watson. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice(s), this list of conditions and the following disclaimer as 11.\" the first lines of this file unmodified other than the possible 12.\" addition of one or more copyright notices. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice(s), this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 18.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 19.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 20.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY 21.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 22.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 23.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 24.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 27.\" DAMAGE. 28.\" 29.\" $FreeBSD: src/share/man/man9/vn_fullpath.9,v 1.2 2004/01/11 19:57:42 rwatson Exp $ 30.\" $DragonFly: src/share/man/man9/vn_fullpath.9,v 1.1 2004/06/03 19:26:36 hmp Exp $ 31.\" 32.Dd June 03, 2004 33.Dt VN_FULLPATH 9 34.Os 35.Sh NAME 36.Nm vn_fullpath 37.Nd construct a pathname by inspecting a vnode's namecache topology 38.Sh SYNOPSIS 39.In sys/param.h 40.In sys/vnode.h 41.Ft int 42.Fn vn_fullpath "struct proc *p" "struct vnode *vn" "char **retbuf" "char **freebuf" 43.Sh DESCRIPTION 44The 45.Nm 46function makes an attempt to generate a string pathname with the 47passed-in vnode, 48.Fa vp . 49The returned path in 50.Fa retbuf 51will be relative to the root directory of the process associated with the 52.Fa p 53argument. 54.Pp 55Its arguments are: 56.Bl -tag -width freebuf 57.It Fa p 58The process performing the call; this pointer will be dereferenced to find 59the process and its file descriptor structure, in order to identify the 60root vnode to use. 61.It Fa vp 62The vnode for constructing the pathname; the vnode is used for enumerating 63its namecache topology. 64If 65.Dv NULL 66is supplied, then it is assumed that the client wants to use the 67vnode of the process image, i.e., 68.Po 69.Va p->p_textvp 70.Pc . 71.It Fa retbuf [out] 72Pointer address to a 73.Va "char *" 74which 75.Nm 76uses for storing the address to a newly allocated buffer, containing the 77constructed pathname. 78.It Fa freebuf 79Auxiliary buffer that is used to by 80.Nm 81for temporary purposes. 82.El 83.Pp 84Typical consumers will declare two character pointers: fullpath and 85freepath; they will set freepath to 86.Dv NULL , 87and fullpath to a name to use 88in the event that the call to 89.Nm 90fails. 91After done with the value of fullpath, the caller will check if freepath 92is non-NULL, and if so, invoke 93.Xr free 9 94with a malloc type of 95.Dv M_TEMP . 96.Sh RETURN VALUES 97If the vnode can be successfully used to construct a pathname, 98.Ql 0 99is returned, otherwise an 100.Li errno 101value is returned. 102.Sh CODE REFERENCES 103All file references in this section are relative to the 104.Dx 105base source directory. 106.Pp 107The 108.Ql "Resident Executables" 109code utilizes the 110.Nm 111function; 112.Pa sys/kern/imgact_resident.c . 113.Sh SEE ALSO 114.Xr free 9 , 115.Xr vnode 9 116.Sh AUTHORS 117.An -nosplit 118This manual page was written by 119.An Robert Watson Aq rwatson@FreeBSD.org 120and adapted for 121.Dx 122by 123.An Hiten Pandya Aq hmp@backplane.com . 124