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.4 2005/08/06 13:34:14 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 77does a generic namecache lookup. 78Note that the passed struct nlookupdata is not nlookup_done()'d on 79return, even if an error occurs. 80If no error occurs the returned nl_ncp is always referenced and 81locked, otherwise it may or may not be. 82Intermediate directory elements, including the current directory, 83require execute (search) permission. 84.Fn nlookup 85does not examine the access permissions on the returned element. 86If NLC_CREATE or NLC_DELETE is set the last directory must allow 87node creation (VCREATE/VDELETE), and an error code of 0 will be 88returned for a non-existant target. 89Otherwise a non-existant target will cause ENOENT to be returned. 90.Pp 91.Fn nlookup_init 92initializes a nlookupdata structure, and does an early error 93return for copyin faults or a degenerate empty string (which is 94not allowed). 95The first process proc0's credentials are used if the calling 96thread is not associated with a process context. 97.Pp 98.Fn nlookup_init_raw 99works similarly to 100.Fn nlookup_init 101but does not assume a process context. 102rootncp is always chosen for the root directory and the cred 103and starting directory are supplied in the arguments. 104.Pp 105.Fn nlookup_set_cred 106sets a different credential; this credential will be used by 107future operations performed on nd.nl_open_vp and the 108nlookupdata structure. 109.Pp 110.Fn nlookup_zero 111zeroes a given nlookupdata structure. 112.Pp 113.Fn nlookup_done 114cleans up a nlookupdata structure after we are through with 115it. 116This function may be called on any nlookupdata structure 117initialized with 118.Fn nlookup_init . 119Calling 120.Fn nlookup_done 121is mandatory in all cases except where 122.Fn nlookup_init 123returns an error, even if as a consumer you believe you 124have taken all dynamic elements out of the nlookupdata 125structure. 126.Pp 127.Fn nlookup_simple 128is a simple all-in-one nlookup. 129It returns a locked namecache structure or NULL if an error 130occured. 131Note that the returned ncp is not checked for permissions, 132though VEXEC is checked on the directory path leading up to 133the result. 134The caller must call 135.Fn naccess 136to check the permissions of the returned leaf. 137.Pp 138.Fn nlookup_mp 139is used to resolve a mount point's glue ncp. 140It creates the illusion of continuity in the namecache tree 141by connecting the ncp related to the vnode under the mount 142to the ncp related to the mount's root vnode. 143If no error occured a locked, ref'd ncp is stored in *ncpp. 144.Pp 145.Fn nreadsymlink 146reads the contents of a symlink, allocates a path buffer out 147of the namei_zone and initialize the supplied nlcomponent 148with the result. 149If an error occurs no buffer will be allocated or returned 150in the nlc. 151.Pp 152.Fn naccess 153generally checks the V* access bits from 154.Pa sys/vnode.h . 155All specified bits must pass for this function to return 0. 156If VCREATE is specified and the target ncp represents a 157non-existant file or dir, or if VDELETE is specified and the 158target exists, the parent directory is checked for VWRITE. 159If VEXCL is specified and the target ncp represents a positive 160hit, an error is returned. 161If VCREATE is not specified and the target does not exist 162(negative hit), ENOENT is returned. 163Note that nlookup() does not (and should not) return ENOENT 164for non-existant leafs. 165The passed ncp may or may not be locked. 166The caller should use a locked ncp on leaf lookups, especially 167for VCREATE, VDELETE, and VEXCL checks. 168.Pp 169.Fn naccess_va 170checks the requested access against the given vattr using cred. 171.Sh BUGS 172This man page needs further work. 173.Sh SEE ALSO 174.Xr VFS 9 , 175.Xr vnode 9 176.Pp 177.Pa src/sys/kern/vfs_nlookup.c 178.Sh AUTHORS 179This man page was written by 180.An Sascha Wildner . 181