[src/trunk]: src/share/man/man9 Document pathbuf_assimilate, used by nfsd to ...

[dholland <dholland%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a8fa590943e0
branches:  trunk
changeset: 759128:a8fa590943e0
user:      dholland <dholland%NetBSD.org@localhost>
date:      Tue Nov 30 10:32:46 2010 +0000

description:
Document pathbuf_assimilate, used by nfsd to move pathnames from mbufs to
pathbufs. It is like pathbuf_create but takes responsibility for the path
buffer passed in. (Because this is asymmetric, it carries an extra risk
of error and therefore shouldn't be used except where it's really needed.)

diffstat:

 share/man/man9/pathbuf.9 |  24 ++++++++++++++++++++++--
 1 files changed, 22 insertions(+), 2 deletions(-)

diffs (57 lines):

diff -r 6ea18c42864b -r a8fa590943e0 share/man/man9/pathbuf.9
--- a/share/man/man9/pathbuf.9  Tue Nov 30 10:29:57 2010 +0000
+++ b/share/man/man9/pathbuf.9  Tue Nov 30 10:32:46 2010 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: pathbuf.9,v 1.1 2010/11/19 06:44:48 dholland Exp $
+.\"     $NetBSD: pathbuf.9,v 1.2 2010/11/30 10:32:46 dholland Exp $
 .\"
 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,12 +27,13 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd November 16, 2010
+.Dd November 30, 2010
 .Dt PATHBUF 9
 .Os
 .Sh NAME
 .Nm pathbuf ,
 .Nm pathbuf_create ,
+.Nm pathbuf_assimilate ,
 .Nm pathbuf_copyin ,
 .Nm pathbuf_destroy
 .Nd path buffer abstraction
@@ -40,6 +41,8 @@
 .In sys/namei.h
 .Ft struct pathbuf *
 .Fn pathbuf_create "const char *path"
+.Ft struct pathbuf *
+.Fn pathbuf_assimilate "char *pnbuf"
 .Ft int
 .Fn pathbuf_copyin "const char *userpath" "struct pathbuf **ret"
 .Ft void
@@ -78,6 +81,23 @@
 It returns an error code.
 .Pp
 The
+.Fn pathbuf_assimilate
+function creates a pathbuf using the string buffer provided as
+.Fa pnbuf .
+This buffer must be of size
+.Dv PATH_MAX
+and must have been allocated with
+.Fn PNBUF_GET .
+The buffer is
+.Dq taken over
+by the returned pathbuf and will be released when the pathbuf is
+destroyed.
+Note: to avoid confusion and pointer bugs,
+.Fn pathbuf_assimilate
+should only be used where absolutely necessary; e.g. the NFS server
+code uses it to generate pathbufs from strings fetched from mbufs.
+.Pp
+The
 .Fn pathbuf_destroy
 function deallocates a pathbuf.
 Caution: because calling