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