Module Name: src
Committed By: dholland
Date: Tue Nov 30 10:32:47 UTC 2010
Modified Files:
src/share/man/man9: pathbuf.9
Log Message:
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.)
To generate a diff of this commit:
cvs rdiff -u -r1.1 -r1.2 src/share/man/man9/pathbuf.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/pathbuf.9
diff -u src/share/man/man9/pathbuf.9:1.1 src/share/man/man9/pathbuf.9:1.2
--- src/share/man/man9/pathbuf.9:1.1 Fri Nov 19 06:44:48 2010
+++ src/share/man/man9/pathbuf.9 Tue Nov 30 10:32:46 2010
@@ -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
