share/man/man9/nlookup.9

   1 .\"
   2 .\" Copyright (c) 2005 The DragonFly Project.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\"
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in
  12 .\"    the documentation and/or other materials provided with the
  13 .\"    distribution.
  14 .\" 3. Neither the name of The DragonFly Project nor the names of its
  15 .\"    contributors may be used to endorse or promote products derived
  16 .\"    from this software without specific, prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  21 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  22 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  24 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  26 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  27 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  28 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .\" $DragonFly: src/share/man/man9/nlookup.9,v 1.11 2008/02/09 09:45:03 swildner Exp $
  32 .\"
  33 .Dd May 26, 2009
  34 .Os
  35 .Dt NLOOKUP 9
  36 .Sh NAME
  37 .Nm nlookup ,
  38 .Nm nlookup_init ,
  39 .Nm nlookup_init_raw ,
  40 .Nm nlookup_set_cred ,
  41 .Nm nlookup_zero ,
  42 .Nm nlookup_done ,
  43 .Nm nlookup_simple ,
  44 .Nm nlookup_mp ,
  45 .Nm nreadsymlink ,
  46 .Nm naccess ,
  47 .Nm naccess_va
  48 .Nd namecache API
  49 .Sh SYNOPSIS
  50 .In sys/types.h
  51 .In sys/nlookup.h
  52 .Ft int
  53 .Fn nlookup "struct nlookupdata *nd"
  54 .Ft int
  55 .Fn nlookup_init "struct nlookupdata *nd" "const char *path" "enum uio_seg seg" "int flags"
  56 .Ft int
  57 .Fn nlookup_init_raw "struct nlookupdata *nd" "const char *path" "enum uio_seg seg" "int flags" "struct ucred *cred" "struct namecache *ncstart"
  58 .Ft void
  59 .Fn nlookup_set_cred "struct nlookupdata *nd" "struct ucred *cred"
  60 .Ft void
  61 .Fn nlookup_zero "struct nlookupdata *nd"
  62 .Ft void
  63 .Fn nlookup_done "struct nlookupdata *nd"
  64 .Ft "struct namecache *"
  65 .Fn nlookup_simple "const char *str" "enum uio_seg seg" "int niflags" "int *error"
  66 .Ft int
  67 .Fn nlookup_mp "struct mount *mp" "struct namecache **ncpp"
  68 .Ft int
  69 .Fn nreadsymlink "struct nlookupdata *nd" "struct namecache *ncp" "struct nlcomponent *nlc"
  70 .Ft int
  71 .Fn naccess "struct namecache *ncp" "int vmode" "struct ucred *cred"
  72 .Ft int
  73 .Fn naccess_va "struct vattr *va" "int vmode" "struct ucred *cred"
  74 .Sh DESCRIPTION
  75 .Fn nlookup
  76 does a generic namecache lookup.
  77 Note that the passed
  78 .Fa "struct nlookupdata"
  79 is not
  80 .Fn nlookup_done Ap d
  81 on return, even if an error occurs.
  82 If no error occurs the returned nl_ncp
  83 is always referenced and locked, otherwise it may or may not be.
  84 Intermediate directory elements, including the current directory,
  85 require execute (search) permission.
  86 .Fn nlookup
  87 does not examine the access permissions on the returned element.
  88 If
  89 .Dv NLC_CREATE
  90 or
  91 .Dv NLC_DELETE
  92 is set the last directory must allow
  93 node creation
  94 .Po
  95 .Dv VCREATE Ns / Ns Dv VDELETE
  96 .Pc ,
  97 and an error code of 0
  98 will be returned for a non-existent target.
  99 Otherwise a non-existent target will cause
 100 .Er ENOENT
 101 to be returned.
 102 .Pp
 103 .Fn nlookup_init
 104 initializes a
 105 .Fa "struct nlookupdata" ,
 106 and does an early error
 107 return for copyin faults or a degenerate empty string (which is
 108 not allowed).
 109 The first process proc0's
 110 credentials are used if the calling
 111 thread is not associated with a process context.
 112 .Pp
 113 .Fn nlookup_init_raw
 114 works similarly to
 115 .Fn nlookup_init
 116 but does not assume a process context.
 117 rootncp is always chosen for the root directory and the
 118 .Fa cred
 119 and starting directory are supplied in the arguments.
 120 .Pp
 121 .Fn nlookup_set_cred
 122 sets a different credential; this credential will be used by
 123 future operations performed on nd.nl_open_vp
 124 and the
 125 .Fa nlookupdata
 126 structure.
 127 .Pp
 128 .Fn nlookup_zero
 129 zeroes a given
 130 .Fa "struct nlookupdata" .
 131 .Pp
 132 .Fn nlookup_done
 133 cleans up an
 134 .Fa nlookupdata
 135 structure after we are through with
 136 it.
 137 This function may be called on any nlookupdata structure
 138 initialized with
 139 .Fn nlookup_init .
 140 Calling
 141 .Fn nlookup_done
 142 is mandatory in all cases except where
 143 .Fn nlookup_init
 144 returns an error, even if as a consumer you believe you
 145 have taken all dynamic elements out of the
 146 .Fa nlookupdata
 147 structure.
 148 .Pp
 149 .Fn nlookup_simple
 150 is a simple all-in-one
 151 .Fn nlookup .
 152 It returns a locked namecache structure or NULL if an error
 153 occurred.
 154 Note that the returned ncp
 155 is not checked for permissions,
 156 though
 157 .Dv VEXEC
 158 is checked on the directory path leading up to
 159 the result.
 160 The caller must call
 161 .Fn naccess
 162 to check the permissions of the returned leaf.
 163 .Pp
 164 .Fn nlookup_mp
 165 is used to resolve a mount point's glue ncp.
 166 It creates the illusion of continuity in the namecache tree
 167 by connecting the ncp related to the vnode under the mount
 168 to the ncp related to the mount's root vnode.
 169 If no error occurred a locked, ref'd ncp is stored in
 170 .Fa *ncpp .
 171 .Pp
 172 .Fn nreadsymlink
 173 reads the contents of a symlink, allocates a path buffer out
 174 of the namei_zone and initialize the supplied nlcomponent
 175 with the result.
 176 If an error occurs no buffer will be allocated or returned
 177 in the nlc.
 178 .Pp
 179 .Fn naccess
 180 generally checks the V* access bits from
 181 .In sys/vnode.h .
 182 All specified bits must pass for this function to return 0.
 183 If
 184 .Dv VCREATE
 185 is specified and the target ncp represents a
 186 non-existent file or dir, or if
 187 .Dv VDELETE
 188 is specified and the
 189 target exists, the parent directory is checked for
 190 .Dv VWRITE .
 191 If
 192 .Dv VEXCL
 193 is specified and the target ncp represents a positive
 194 hit, an error is returned.
 195 If
 196 .Dv VCREATE
 197 is not specified and the target does not exist
 198 (negative hit),
 199 .Er ENOENT
 200 is returned.
 201 Note that
 202 .Fn nlookup
 203 does not (and should not) return
 204 .Er ENOENT
 205 for non-existent leafs.
 206 The passed ncp may or may not be locked.
 207 The caller should use a locked ncp on leaf lookups, especially
 208 for
 209 .Dv VCREATE ,
 210 .Dv VDELETE ,
 211 and
 212 .Dv VEXCL
 213 checks.
 214 .Pp
 215 .Fn naccess_va
 216 checks the requested access against the given
 217 .Fa vattr
 218 using
 219 .Fa cred .
 220 .Sh FILES
 221 .Pa sys/kern/vfs_nlookup.c
 222 .Sh SEE ALSO
 223 .Xr VFS 9 ,
 224 .Xr vnode 9
 225 .Sh AUTHORS
 226 This man page was written by
 227 .An Sascha Wildner .