From d7cb6c2522be5f5c5238b0f09eafa224e84b8483 Mon Sep 17 00:00:00 2001 From: Sascha Wildner Date: Sat, 6 Aug 2005 12:42:42 +0000 Subject: [PATCH] Add nlookup(9) man page. --- share/man/man9/Makefile | 14 ++- share/man/man9/nlookup.9 | 184 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 197 insertions(+), 1 deletion(-) create mode 100644 share/man/man9/nlookup.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index c1f8048885..ac62223399 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,5 +1,5 @@ # $FreeBSD: src/share/man/man9/Makefile,v 1.60.2.26 2003/06/13 01:04:17 hmp Exp $ -# $DragonFly: src/share/man/man9/Makefile,v 1.21 2005/08/06 11:36:13 swildner Exp $ +# $DragonFly: src/share/man/man9/Makefile,v 1.22 2005/08/06 12:42:42 swildner Exp $ MAN= DECLARE_MODULE.9 DELAY.9 DEV_MODULE.9 KASSERT.9 MD5.9 \ MODULE_DEPEND.9 MODULE_VERSION.9 SPLASSERT.9 SYSCALL_MODULE.9 \ @@ -25,6 +25,7 @@ MAN= DECLARE_MODULE.9 DELAY.9 DEV_MODULE.9 KASSERT.9 MD5.9 \ ieee80211_radiotap.9 \ ifnet.9 inittodr.9 intro.9 kernacc.9 ktr.9 lock.9 \ malloc.9 make_dev.9 mbuf.9 microseq.9 mi_switch.9 module.9 namei.9 \ + nlookup.9 \ pci.9 panic.9 physio.9 posix4.9 psignal.9 \ resettodr.9 \ rman.9 \ @@ -245,6 +246,17 @@ MLINKS+=microtime.9 getnanotime.9 MLINKS+=microuptime.9 getmicrouptime.9 microuptime.9 nanouptime.9 MLINKS+=microuptime.9 getnanouptime.9 +MLINKS+=nlookup.9 nlookup_init.9 +MLINKS+=nlookup.9 nlookup_init_raw.9 +MLINKS+=nlookup.9 nlookup_set_cred.9 +MLINKS+=nlookup.9 nlookup_zero.9 +MLINKS+=nlookup.9 nlookup_done.9 +MLINKS+=nlookup.9 nlookup_simple.9 +MLINKS+=nlookup.9 nlookup_mp.9 +MLINKS+=nlookup.9 nreadsymlink.9 +MLINKS+=nlookup.9 naccess.9 +MLINKS+=nlookup.9 naccess_va.9 + MLINKS+=sysctl_add_oid.9 sysctl_remove_oid.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_OID.9 MLINKS+=sysctl_add_oid.9 SYSCTL_ADD_NODE.9 diff --git a/share/man/man9/nlookup.9 b/share/man/man9/nlookup.9 new file mode 100644 index 0000000000..a4902fea44 --- /dev/null +++ b/share/man/man9/nlookup.9 @@ -0,0 +1,184 @@ +.\" +.\" The software known as "DragonFly" or "DragonFly BSD" is distributed under +.\" the following terms: +.\" +.\" Copyright (c) 2003, 2004, 2005 The DragonFly Project. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" 3. Neither the name of The DragonFly Project nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific, prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $DragonFly: src/share/man/man9/nlookup.9,v 1.1 2005/08/06 12:42:42 swildner Exp $ +.\" +.Dd August 6, 2005 +.Os +.Dt NLOOKUP 9 +.Sh NAME +.Nm nlookup , +.Nm nlookup_init , +.Nm nlookup_init_raw , +.Nm nlookup_set_cred , +.Nm nlookup_zero , +.Nm nlookup_done , +.Nm nlookup_simple , +.Nm nlookup_mp , +.Nm nreadsymlink , +.Nm naccess , +.Nm naccess_va +.Nd namecache API +.Sh SYNOPSIS +.In sys/types.h +.In sys/nlookup.h +.Ft int +.Fn nlookup "struct nlookupdata *nd" +.Ft int +.Fn nlookup_init "struct nlookupdata *nd" "const char *path" "enum uio_seg seg" "int flags" +.Ft int +.Fn nlookup_init_raw "struct nlookupdata *nd" "const char *path" "enum uio_seg seg" "int flags" "struct ucred *cred" "struct namecache *ncstart" +.Ft void +.Fn nlookup_set_cred "struct nlookupdata *nd" "struct ucred *cred" +.Ft void +.Fn nlookup_zero "struct nlookupdata *nd" +.Ft void +.Fn nlookup_done "struct nlookupdata *nd" +.Ft "struct namecache *" +.Fn nlookup_simple "const char *str" "enum uio_seg seg" "int niflags" "int *error" +.Ft int +.Fn nlookup_mp "struct mount *mp" "struct namecache **ncpp" +.Ft int +.Fn nreadsymlink "struct nlookupdata *nd" "struct namecache *ncp" "struct nlcomponent *nlc" +.Ft int +.Fn naccess "struct namecache *ncp" "int vmode" "struct ucred *cred" +.Ft int +.Fn naccess_va "struct vattr *va" "int vmode" "struct ucred *cred" +.Sh DESCRIPTION +.Fn nlookup +does a generic namecache lookup. +Note that the passed struct nlookupdata is not nlookup_done()'d on +return, even if an error occurs. +If no error occurs the returned nl_ncp is always referenced and +locked, otherwise it may or may not be. +Intermediate directory elements, including the current directory, +require execute (search) permission. +.Fn nlookup +does not examine the access permissions on the returned element. +If NLC_CREATE or NLC_DELETE is set the last directory must allow +node creation (VCREATE/VDELETE), and an error code of 0 will be +returned for a non-existant target. +Otherwise a non-existant target will cause ENOENT to be returned. +.Pp +.Fn nlookup_init +initializes a nlookupdata structure, and does an early error +return for copyin faults or a degenerate empty string (which is +not allowed). +The first process proc0's credentials are used if the calling +thread is not associated with a process context. +.Pp +.Fn nlookup_init_raw +works similarly to +.Fn nlookup_init +but does not assume a process context. +rootncp is always chosen for the root directory and the cred +and starting directory are supplied in the arguments. +.Pp +.Fn nlookup_set_cred +sets a different credential; this credential will be used by +future operations performed on nd.nl_open_vp and the +nlookupdata structure. +.Pp +.Fn nlookup_zero +zeroes a given nlookupdata structure. +.Pp +.Fn nlookup_done +cleans up a nlookupdata structure after we are through with +it. +This function may be called on any nlookupdata structure +initialized with +.Fn nlookup_init . +Calling +.Fn nlookup_done +is mandatory in all cases except where +.Fn nlookup_init +returns an error, even if as a consumer you believe you +have taken all dynamic elements out of the nlookupdata +structure. +.Pp +.Fn nlookup_simple +is a simple all-in-one nlookup. +It returns a locked namecache structure or NULL if an error +occured. +Note that the returned ncp is not checked for permissions, +though VEXEC is checked on the directory path leading up to +the result. +The caller must call +.Fn naccess +to check the permissions of the returned leaf. +.Pp +.Fn nlookup_mp +is used to resolve a mount point's glue ncp. +It creates the illusion of continuity in the namecache tree +by connecting the ncp related to the vnode under the mount +to the ncp related to the mount's root vnode. +If no error occured a locked, ref'd ncp is stored in *ncpp. +.Pp +.Fn nreadsymlink +reads the contents of a symlink, allocates a path buffer out +of the namei_zone and initialize the supplied nlcomponent +with the result. +If an error occurs no buffer will be allocated or returned +in the nlc. +.Pp +.Fn naccess +generally checks the V* access bits from +.Pa sys/vnode.h . +All specified bits must pass for this function to return 0. +If VCREATE is specified and the target ncp represents a +non-existant file or dir, or if VDELETE is specified and the +target exists, the parent directory is checked for VWRITE. +If VEXCL is specified and the target ncp represents a positive +hit, an error is returned. +If VCREATE is not specified and the target does not exist +(negative hit), ENOENT is returned. +Note that nlookup() does not (and should not) return ENOENT +for non-existant leafs. +The passed ncp may or may not be locked. +The caller should use a locked ncp on leaf lookups, especially +for VCREATE, VDELETE, and VEXCL checks. +.Pp +.Fn naccess_va +checks the requested access against the given vattr using cred. +.Sh BUGS +This man page needs further work. +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vnode 9 +.Pp +.Pa src/sys/kern/vfs_nlookup.c +.Sh AUTHORS +This man page was written by +.An Sascha Wildner +taking Matt Dillon's comments in +.Pa src/sys/kern/vfs_nlookup.c . -- 2.41.0