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