xref: /dragonfly/share/man/man9/nlookup.9 (revision 8a7bdfea) 
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.11 2008/02/09 09:45:03 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-existent target.
100Otherwise a non-existent 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
152.Fn nlookup .
153It returns a locked namecache structure or NULL if an error
154occurred.
155Note that the returned ncp
156is not checked for permissions,
157though
158.Dv VEXEC
159is checked on the directory path leading up to
160the result.
161The caller must call
162.Fn naccess
163to check the permissions of the returned leaf.
164.Pp
165.Fn nlookup_mp
166is used to resolve a mount point's glue ncp.
167It creates the illusion of continuity in the namecache tree
168by connecting the ncp related to the vnode under the mount
169to the ncp related to the mount's root vnode.
170If no error occurred a locked, ref'd ncp is stored in
171.Fa *ncpp .
172.Pp
173.Fn nreadsymlink
174reads the contents of a symlink, allocates a path buffer out
175of the namei_zone and initialize the supplied nlcomponent
176with the result.
177If an error occurs no buffer will be allocated or returned
178in the nlc.
179.Pp
180.Fn naccess
181generally checks the V* access bits from
182.In sys/vnode.h .
183All specified bits must pass for this function to return 0.
184If
185.Dv VCREATE
186is specified and the target ncp represents a
187non-existent file or dir, or if
188.Dv VDELETE
189is specified and the
190target exists, the parent directory is checked for
191.Dv VWRITE .
192If
193.Dv VEXCL
194is specified and the target ncp represents a positive
195hit, an error is returned.
196If
197.Dv VCREATE
198is not specified and the target does not exist
199(negative hit),
200.Er ENOENT
201is returned.
202Note that
203.Fn nlookup
204does not (and should not) return
205.Er ENOENT
206for non-existent leafs.
207The passed ncp may or may not be locked.
208The caller should use a locked ncp on leaf lookups, especially
209for
210.Dv VCREATE ,
211.Dv VDELETE ,
212and
213.Dv VEXCL
214checks.
215.Pp
216.Fn naccess_va
217checks the requested access against the given
218.Fa vattr
219using
220.Fa cred .
221.Sh SEE ALSO
222.Xr VFS 9 ,
223.Xr vnode 9
224.Pp
225.Pa src/sys/kern/vfs_nlookup.c
226.Sh AUTHORS
227This man page was written by
228.An Sascha Wildner .
229.Sh BUGS
230This man page needs further work.
231