share/man/man9/vn_fullpath.9

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