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 .Dd August 1, 2010
  32 .Dt NLOOKUP 9
  33 .Os
  34 .Sh NAME
  35 .Nm nlookup ,
  36 .Nm nlookup_init ,
  37 .Nm nlookup_init_at ,
  38 .Nm nlookup_init_raw ,
  39 .Nm nlookup_init_root ,
  40 .Nm nlookup_set_cred ,
  41 .Nm nlookup_zero ,
  42 .Nm nlookup_done ,
  43 .Nm nlookup_done_at ,
  44 .Nm nlookup_simple ,
  45 .Nm nlookup_mp ,
  46 .Nm nreadsymlink ,
  47 .Nm naccess ,
  48 .Nm naccess_va
  49 .Nd namecache API
  50 .Sh SYNOPSIS
  51 .In sys/types.h
  52 .In sys/nlookup.h
  53 .Ft int
  54 .Fn nlookup "struct nlookupdata *nd"
  55 .Ft int
  56 .Fn nlookup_init "struct nlookupdata *nd" "const char *path" "enum uio_seg seg" "int flags"
  57 .Ft int
  58 .Fn nlookup_init_at "struct nlookupdata *nd" "struct file **fpp" "int fd" "const char *path" "enum uio_seg seg" "int flags"
  59 .Ft int
  60 .Fn nlookup_init_raw "struct nlookupdata *nd" "const char *path" "enum uio_seg seg" "int flags" "struct ucred *cred" "struct namecache *ncstart"
  61 .Ft int
  62 .Fn nlookup_init_root "struct nlookupdata *nd" "const char *path" "enum uio_seg seg" "int flags" "struct ucred *cred" "struct namecache *ncstart" "struct namecache *ncroot"
  63 .Ft void
  64 .Fn nlookup_set_cred "struct nlookupdata *nd" "struct ucred *cred"
  65 .Ft void
  66 .Fn nlookup_zero "struct nlookupdata *nd"
  67 .Ft void
  68 .Fn nlookup_done "struct nlookupdata *nd"
  69 .Ft void
  70 .Fn nlookup_done_at "struct nlookupdata *nd" "struct file *fp"
  71 .Ft "struct namecache *"
  72 .Fn nlookup_simple "const char *str" "enum uio_seg seg" "int niflags" "int *error"
  73 .Ft int
  74 .Fn nlookup_mp "struct mount *mp" "struct namecache **ncpp"
  75 .Ft int
  76 .Fn nreadsymlink "struct nlookupdata *nd" "struct namecache *ncp" "struct nlcomponent *nlc"
  77 .Ft int
  78 .Fn naccess "struct namecache *ncp" "int vmode" "struct ucred *cred"
  79 .Ft int
  80 .Fn naccess_va "struct vattr *va" "int vmode" "struct ucred *cred"
  81 .Sh DESCRIPTION
  82 .Fn nlookup
  83 does a generic namecache lookup.
  84 Note that the passed
  85 .Fa "struct nlookupdata"
  86 is not
  87 .Fn nlookup_done Ap d
  88 on return, even if an error occurs.
  89 If no error occurs the returned nl_ncp
  90 is always referenced and locked, otherwise it may or may not be.
  91 Intermediate directory elements, including the current directory,
  92 require execute (search) permission.
  93 .Fn nlookup
  94 does not examine the access permissions on the returned element.
  95 If
  96 .Dv NLC_CREATE
  97 or
  98 .Dv NLC_DELETE
  99 is set the last directory must allow
 100 node creation
 101 .Po
 102 .Dv VCREATE Ns / Ns Dv VDELETE
 103 .Pc ,
 104 and an error code of 0
 105 will be returned for a non-existent target.
 106 Otherwise a non-existent target will cause
 107 .Er ENOENT
 108 to be returned.
 109 .Pp
 110 .Fn nlookup_init
 111 initializes a
 112 .Fa "struct nlookupdata" ,
 113 and does an early error
 114 return for copyin faults or a degenerate empty string (which is
 115 not allowed).
 116 The first process proc0's
 117 credentials are used if the calling
 118 thread is not associated with a process context.
 119 .Pp
 120 .Fn nlookup_init_at
 121 is similar to
 122 .Fn nlookup_init
 123 except that when
 124 .Fa path
 125 is a relative path and
 126 .Fa fd
 127 is not
 128 .Dv AT_FDCWD ,
 129 .Fa path
 130 is interpreted relative to the directory associated with
 131 .Fa fd
 132 and the file entry for
 133 .Fa fd
 134 is referenced and returned in
 135 .Fa *fpp .
 136 Its main use is the implementation of
 137 .Fn *at
 138 system calls.
 139 .Pp
 140 .Fn nlookup_init_raw
 141 works similarly to
 142 .Fn nlookup_init
 143 but does not assume a process context.
 144 rootncp is always chosen for the root directory and the
 145 .Fa cred
 146 and starting directory are supplied in the arguments.
 147 .Pp
 148 .Fn nlookup_init_root
 149 works similarly to
 150 .Fn nlookup_init_raw
 151 but does not assume rootnch for the root directory.
 152 The root directory is supplied in the arguments, and is also
 153 used for the jail directory.
 154 .Pp
 155 .Fn nlookup_set_cred
 156 sets a different credential; this credential will be used by
 157 future operations performed on nd.nl_open_vp
 158 and the
 159 .Fa nlookupdata
 160 structure.
 161 .Pp
 162 .Fn nlookup_zero
 163 zeroes a given
 164 .Fa "struct nlookupdata" .
 165 .Pp
 166 .Fn nlookup_done
 167 cleans up an
 168 .Fa nlookupdata
 169 structure after we are through with
 170 it.
 171 This function may be called on any nlookupdata structure
 172 initialized with
 173 .Fn nlookup_init .
 174 Calling
 175 .Fn nlookup_done
 176 is mandatory in all cases except where
 177 .Fn nlookup_init
 178 returns an error, even if as a consumer you believe you
 179 have taken all dynamic elements out of the
 180 .Fa nlookupdata
 181 structure.
 182 .Pp
 183 .Fn nlookup_done_at
 184 cleans up an
 185 .Fa nlookupdata
 186 structure that was initialized with
 187 .Fn nlookup_init_at
 188 and drops the reference to
 189 .Fa fp .
 190 .Pp
 191 .Fn nlookup_simple
 192 is a simple all-in-one
 193 .Fn nlookup .
 194 It returns a locked namecache structure or NULL if an error
 195 occurred.
 196 Note that the returned ncp
 197 is not checked for permissions,
 198 though
 199 .Dv VEXEC
 200 is checked on the directory path leading up to
 201 the result.
 202 The caller must call
 203 .Fn naccess
 204 to check the permissions of the returned leaf.
 205 .Pp
 206 .Fn nlookup_mp
 207 is used to resolve a mount point's glue ncp.
 208 It creates the illusion of continuity in the namecache tree
 209 by connecting the ncp related to the vnode under the mount
 210 to the ncp related to the mount's root vnode.
 211 If no error occurred a locked, ref'd ncp is stored in
 212 .Fa *ncpp .
 213 .Pp
 214 .Fn nreadsymlink
 215 reads the contents of a symlink, allocates a path buffer out
 216 of the namei_zone and initialize the supplied nlcomponent
 217 with the result.
 218 If an error occurs no buffer will be allocated or returned
 219 in the nlc.
 220 .Pp
 221 .Fn naccess
 222 generally checks the V* access bits from
 223 .In sys/vnode.h .
 224 All specified bits must pass for this function to return 0.
 225 If
 226 .Dv VCREATE
 227 is specified and the target ncp represents a
 228 non-existent file or dir, or if
 229 .Dv VDELETE
 230 is specified and the
 231 target exists, the parent directory is checked for
 232 .Dv VWRITE .
 233 If
 234 .Dv VEXCL
 235 is specified and the target ncp represents a positive
 236 hit, an error is returned.
 237 If
 238 .Dv VCREATE
 239 is not specified and the target does not exist
 240 (negative hit),
 241 .Er ENOENT
 242 is returned.
 243 Note that
 244 .Fn nlookup
 245 does not (and should not) return
 246 .Er ENOENT
 247 for non-existent leafs.
 248 The passed ncp may or may not be locked.
 249 The caller should use a locked ncp on leaf lookups, especially
 250 for
 251 .Dv VCREATE ,
 252 .Dv VDELETE ,
 253 and
 254 .Dv VEXCL
 255 checks.
 256 .Pp
 257 .Fn naccess_va
 258 checks the requested access against the given
 259 .Fa vattr
 260 using
 261 .Fa cred .
 262 .Sh FILES
 263 .Pa sys/kern/vfs_nlookup.c
 264 .Sh SEE ALSO
 265 .Xr VFS 9 ,
 266 .Xr vnode 9
 267 .Sh AUTHORS
 268 This man page was written by
 269 .An Sascha Wildner .