2 .\" The software known as "DragonFly" or "DragonFly BSD" is distributed under
3 .\" the following terms:
5 .\" Copyright (c) 2003, 2004, 2005 The DragonFly Project. All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in
15 .\" the documentation and/or other materials provided with the
17 .\" 3. Neither the name of The DragonFly Project nor the names of its
18 .\" contributors may be used to endorse or promote products derived
19 .\" from this software without specific, prior written permission.
21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
27 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
29 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
31 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" $DragonFly: src/share/man/man9/nlookup.9,v 1.1 2005/08/06 12:42:42 swildner Exp $
42 .Nm nlookup_init_raw ,
43 .Nm nlookup_set_cred ,
56 .Fn nlookup "struct nlookupdata *nd"
58 .Fn nlookup_init "struct nlookupdata *nd" "const char *path" "enum uio_seg seg" "int flags"
60 .Fn nlookup_init_raw "struct nlookupdata *nd" "const char *path" "enum uio_seg seg" "int flags" "struct ucred *cred" "struct namecache *ncstart"
62 .Fn nlookup_set_cred "struct nlookupdata *nd" "struct ucred *cred"
64 .Fn nlookup_zero "struct nlookupdata *nd"
66 .Fn nlookup_done "struct nlookupdata *nd"
67 .Ft "struct namecache *"
68 .Fn nlookup_simple "const char *str" "enum uio_seg seg" "int niflags" "int *error"
70 .Fn nlookup_mp "struct mount *mp" "struct namecache **ncpp"
72 .Fn nreadsymlink "struct nlookupdata *nd" "struct namecache *ncp" "struct nlcomponent *nlc"
74 .Fn naccess "struct namecache *ncp" "int vmode" "struct ucred *cred"
76 .Fn naccess_va "struct vattr *va" "int vmode" "struct ucred *cred"
79 does a generic namecache lookup.
80 Note that the passed struct nlookupdata is not nlookup_done()'d on
81 return, even if an error occurs.
82 If no error occurs the returned nl_ncp is always referenced and
83 locked, otherwise it may or may not be.
84 Intermediate directory elements, including the current directory,
85 require execute (search) permission.
87 does not examine the access permissions on the returned element.
88 If NLC_CREATE or NLC_DELETE is set the last directory must allow
89 node creation (VCREATE/VDELETE), and an error code of 0 will be
90 returned for a non-existant target.
91 Otherwise a non-existant target will cause ENOENT to be returned.
94 initializes a nlookupdata structure, and does an early error
95 return for copyin faults or a degenerate empty string (which is
97 The first process proc0's credentials are used if the calling
98 thread is not associated with a process context.
103 but does not assume a process context.
104 rootncp is always chosen for the root directory and the cred
105 and starting directory are supplied in the arguments.
108 sets a different credential; this credential will be used by
109 future operations performed on nd.nl_open_vp and the
110 nlookupdata structure.
113 zeroes a given nlookupdata structure.
116 cleans up a nlookupdata structure after we are through with
118 This function may be called on any nlookupdata structure
123 is mandatory in all cases except where
125 returns an error, even if as a consumer you believe you
126 have taken all dynamic elements out of the nlookupdata
130 is a simple all-in-one nlookup.
131 It returns a locked namecache structure or NULL if an error
133 Note that the returned ncp is not checked for permissions,
134 though VEXEC is checked on the directory path leading up to
138 to check the permissions of the returned leaf.
141 is used to resolve a mount point's glue ncp.
142 It creates the illusion of continuity in the namecache tree
143 by connecting the ncp related to the vnode under the mount
144 to the ncp related to the mount's root vnode.
145 If no error occured a locked, ref'd ncp is stored in *ncpp.
148 reads the contents of a symlink, allocates a path buffer out
149 of the namei_zone and initialize the supplied nlcomponent
151 If an error occurs no buffer will be allocated or returned
155 generally checks the V* access bits from
157 All specified bits must pass for this function to return 0.
158 If VCREATE is specified and the target ncp represents a
159 non-existant file or dir, or if VDELETE is specified and the
160 target exists, the parent directory is checked for VWRITE.
161 If VEXCL is specified and the target ncp represents a positive
162 hit, an error is returned.
163 If VCREATE is not specified and the target does not exist
164 (negative hit), ENOENT is returned.
165 Note that nlookup() does not (and should not) return ENOENT
166 for non-existant leafs.
167 The passed ncp may or may not be locked.
168 The caller should use a locked ncp on leaf lookups, especially
169 for VCREATE, VDELETE, and VEXCL checks.
172 checks the requested access against the given vattr using cred.
174 This man page needs further work.
179 .Pa src/sys/kern/vfs_nlookup.c
181 This man page was written by
183 taking Matt Dillon's comments in
184 .Pa src/sys/kern/vfs_nlookup.c .