Add a manual page which describes the vn_fullpath(9) function.
[dragonfly.git] / share / man / man9 / vn_fullpath.9
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
44 The
45 .Nm
46 function makes an attempt to generate a string pathname with the
47 passed-in vnode,
48 .Fa vp .
49 The returned path in
50 .Fa retbuf
51 will be relative to the root directory of the process associated with the
52 .Fa p
53 argument.
54 .Pp
55 Its arguments are:
56 .Bl -tag -width freebuf
57 .It Fa p
58 The process performing the call; this pointer will be dereferenced to find
59 the process and its file descriptor structure, in order to identify the
60 root vnode to use.
61 .It Fa vp
62 The vnode for constructing the pathname; the vnode is used for enumerating
63 its namecache topology.
64 If
65 .Dv NULL
66 is supplied, then it is assumed that the client wants to use the
67 vnode of the process image, i.e.,
68 .Po
69 .Va p->p_textvp
70 .Pc .
71 .It Fa retbuf [out]
72 Pointer address to a
73 .Va "char *"
74 which
75 .Nm
76 uses for storing the address to a newly allocated buffer, containing the
77 constructed pathname.
78 .It Fa freebuf
79 Auxiliary buffer that is used to by
80 .Nm
81 for temporary purposes.
82 .El
83 .Pp
84 Typical consumers will declare two character pointers: fullpath and
85 freepath; they will set freepath to
86 .Dv NULL ,
87 and fullpath to a name to use
88 in the event that the call to
89 .Nm
90 fails.
91 After done with the value of fullpath, the caller will check if freepath
92 is non-NULL, and if so, invoke
93 .Xr free 9
94 with a malloc type of
95 .Dv M_TEMP .
96 .Sh RETURN VALUES
97 If the vnode can be successfully used to construct a pathname,
98 .Ql 0
99 is returned, otherwise an
100 .Li errno
101 value is returned.
102 .Sh CODE REFERENCES
103 All file references in this section are relative to the
104 .Dx
105 base source directory.
106 .Pp
107 The
108 .Ql "Resident Executables"
109 code utilizes the
110 .Nm
111 function;
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
118 This manual page was written by
119 .An Robert Watson Aq rwatson@FreeBSD.org
120 and adapted for
121 .Dx
122 by
123 .An Hiten Pandya Aq hmp@backplane.com .