Fix forgotten comma from last commit.
[dragonfly.git] / share / man / man9 / nlookup.9
CommitLineData
d7cb6c25 1.\"
00b1b402 2.\" Copyright (c) 2005 The DragonFly Project. All rights reserved.
d7cb6c25
SW
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.\"
5e3cd055 31.\" $DragonFly: src/share/man/man9/nlookup.9,v 1.4 2005/08/06 13:34:14 swildner Exp $
d7cb6c25
SW
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 ,
5e3cd055 47.Nm naccess_va ,
84852cb9 48.Nm namei
d7cb6c25
SW
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
00b1b402 180.An Sascha Wildner .