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 .\"
  62 .Dd June 3, 2004
  63 .Dt VN_FULLPATH 9
  64 .Os
  65 .Sh NAME
  66 .Nm vn_fullpath
  67 .Nd construct a pathname by inspecting a vnode's namecache topology
  68 .Sh SYNOPSIS
  69 .In sys/param.h
  70 .In sys/vnode.h
  71 .Ft int
  72 .Fn vn_fullpath "struct proc *p" "struct vnode *vp" "char **retbuf" "char **freebuf" "int guess"
  73 .Sh DESCRIPTION
  74 The
  75 .Nm
  76 function makes an attempt to generate a string pathname with the
  77 passed-in vnode,
  78 .Fa vp .
  79 The returned path in
  80 .Fa retbuf
  81 will be relative to the root directory of the process associated with the
  82 .Fa p
  83 argument.
  84 .Pp
  85 Its arguments are:
  86 .Bl -tag -width freebuf
  87 .It Fa p
  88 The process performing the call; this pointer will be dereferenced to find
  89 the process and its file descriptor structure, in order to identify the
  90 root vnode to use.
  91 .It Fa vp
  92 The vnode for constructing the pathname; the vnode is used for enumerating
  93 its namecache topology.
  94 If
  95 .Dv NULL
  96 is supplied, then it is assumed that the client wants to use the
  97 vnode of the process image, i.e.,
  98 .Po
  99 .Va p->p_textvp
 100 .Pc .
 101 .It Fa retbuf [out]
 102 Pointer address to a
 103 .Va "char *"
 104 which
 105 .Nm
 106 uses for storing the address to a newly allocated buffer, containing the
 107 constructed pathname.
 108 .It Fa freebuf
 109 Auxiliary buffer that is used to by
 110 .Nm
 111 for temporary purposes.
 112 .It Fa guess
 113 If guess is not 0, the mountpoint will be guessed if it can't be determined when
 114 traversing the namecache entries upwards.
 115 .El
 116 .Pp
 117 Typical consumers will declare two character pointers: fullpath and
 118 freepath; they will set freepath to
 119 .Dv NULL ,
 120 and fullpath to a name to use
 121 in the event that the call to
 122 .Nm
 123 fails.
 124 After done with the value of fullpath, the caller will check if freepath
 125 is non-NULL, and if so, invoke
 126 .Xr kfree 9
 127 with a malloc type of
 128 .Dv M_TEMP .
 129 .Sh RETURN VALUES
 130 If the vnode can be successfully used to construct a pathname,
 131 .Ql 0
 132 is returned, otherwise an
 133 .Va errno
 134 value is returned.
 135 .Sh CODE REFERENCES
 136 All file references in this section are relative to the
 137 .Dx
 138 base source directory.
 139 .Pp
 140 The
 141 .Ql "Resident Executables"
 142 code utilizes the
 143 .Nm
 144 function;
 145 .Pa sys/kern/imgact_resident.c .
 146 .Sh SEE ALSO
 147 .Xr kfree 9 ,
 148 .Xr vnode 9
 149 .Sh AUTHORS
 150 .An -nosplit
 151 This manual page was written by
 152 .An Robert Watson Aq Mt rwatson@FreeBSD.org
 153 and adapted for
 154 .Dx
 155 by
 156 .An Hiten Pandya Aq Mt hmp@backplane.com .