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.6 2007/06/30 19:03:52 swildner Exp $
  62 .\"
  63 .Dd June 3, 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 *vp" "char **retbuf" "char **freebuf" "int guess"
  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 .It Fa guess
 114 If guess is not 0, the mountpoint will be guessed if it can't be determined when
 115 traversing the namecache entries upwards.
 116 .El
 117 .Pp
 118 Typical consumers will declare two character pointers: fullpath and
 119 freepath; they will set freepath to
 120 .Dv NULL ,
 121 and fullpath to a name to use
 122 in the event that the call to
 123 .Nm
 124 fails.
 125 After done with the value of fullpath, the caller will check if freepath
 126 is non-NULL, and if so, invoke
 127 .Xr kfree 9
 128 with a malloc type of
 129 .Dv M_TEMP .
 130 .Sh RETURN VALUES
 131 If the vnode can be successfully used to construct a pathname,
 132 .Ql 0
 133 is returned, otherwise an
 134 .Va errno
 135 value is returned.
 136 .Sh CODE REFERENCES
 137 All file references in this section are relative to the
 138 .Dx
 139 base source directory.
 140 .Pp
 141 The
 142 .Ql "Resident Executables"
 143 code utilizes the
 144 .Nm
 145 function;
 146 .Pa sys/kern/imgact_resident.c .
 147 .Sh SEE ALSO
 148 .Xr kfree 9 ,
 149 .Xr vnode 9
 150 .Sh AUTHORS
 151 .An -nosplit
 152 This manual page was written by
 153 .An Robert Watson Aq rwatson@FreeBSD.org
 154 and adapted for
 155 .Dx
 156 by
 157 .An Hiten Pandya Aq hmp@backplane.com .