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