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