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