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