Document NDFREE w/flags, and fix up the description of NOFOLLOW.

1 files changed, 49 insertions, 11 deletions

diff --git a/share/man/man9/namei.9 b/share/man/man9/namei.9
index aa3f0913700b..a8766dd88370 100644
--- a/share/man/man9/namei.9
+++ b/share/man/man9/namei.9
@@ -1,6 +1,6 @@
 .\" -*- nroff -*-
 .\"
-.\" Copyright (c) 1998 Eivind Eklund
+.\" Copyright (c) 1998, 1999 Eivind Eklund
 .\"
 .\" All rights reserved.
 .\"
@@ -32,7 +32,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd September 26th, 1998
+.Dd December 16th, 1998
 .Os
 .Dt NAMEI 9
 .Sh NAME
@@ -46,6 +46,7 @@
 .Fn namei "struct nameidata *ndp"
 .Ft void
 .Fn NDINIT "struct nameidata *ndp" "int operation" "int operflags" "int segflag" "const char *path" "struct proc *proc"
+.Fn NDFREE "struct nameidata *ndp" "int operflags"
 
 .Sh DESCRIPTION
 
@@ -143,16 +144,53 @@ Do not call
 for the returned vnode even if it is
 just a VREG and we're able to (ie, it is locked).
 .It Dv NOFOLLOW
-Do not follow symbolic links (pseudo).  This flag does not seem to be
-honoured by the actual code.
+Do not follow symbolic links (pseudo).
+This flag is not looked for by the actual code, which looks for
+FOLLOW.
+NOFOLLOW is used to indicate to the source code reader that symlinks
+are intentionally not followed.
 .El
-.Sh BUGS
-.Fn namei
-calls
-.Fn lookup
-for each component in the pathname, instead of
-handing the actual names onwards to the stacking layers.  This hinders
-the implementation of stacking layers that do full namespace escapes.
+.Sh ALLOCATED ELEMENTS
+.Bl -tag -width WANTPARENT
+.It Dv ni_startdir
+Where we did lookup relative to.
+In the normal case, this is either the current directory or the root.
+It is the current directory if the name passed in doesn't start with /
+and we have not gone through any symlinks with an absolute path, and
+the root otherwise.
+
+In this case, it is is only used by lookup(), and should not be
+considered valid after a call to namei().
+
+If SAVESTART is set, this is set to the same as ni_dvp, with an extra
+VREF().
+
+To block NDFREE from releasing ni_startdir when it is set, use the
+flag NDF_NO_STARTDIR_RELE.
+
+.It Dv ni_dvp
+The directory vp for the directory the object we're looking up is in.
+This is available on successful return if LOCKPARENT or WANTPARENT is
+set.  It is locked if LOCKPARENT is set.  Freeing this in NDFREE can
+be inhibited by NDF_NO_DVP_RELE, NDF_NO_DVP_PUT, or NDF_NO_DVP_UNLOCK
+(with the obvious effects).
+.It Dv ni_vp
+The vp for the target of the of the pathname exists, NULL otherwise.
+The vp is returned with increased reference count (VREF'ed).  If
+LOCKLEAF is set, it is also locked.
+
+Freeing this in NDFREE can be inhibited by NDF_NO_VP_RELE,
+NDF_NO_VP_PUT, or NDF_NO_VP_UNLOCK (with the obvious effects).
+
+.It Dv ni_cnd.cn_pnbuf
+Path name buffer.  This is allocated through zalloc(namei_zone)
+and freed through zfree(namei_zone, ...).
+
+This is available to the caller (who must free it using
+.Xr NDFREE 9 )
+if SAVESTART or SAVENAME is set.
+To free only the ni_cnd.cn_pnbuf, there is a special flags NDF_ONLY_PNBUF.
+To not free the cnd, use the flag ND_NO_FREE_PNBUF.
 .Sh SEE ALSO
 .Xr VFS 9 ,
 .Xr vnode 9 ,