.\"     $NetBSD: pathbuf.9,v 1.2 2010/11/30 10:32:46 dholland Exp $
.\"
.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by David A. Holland.
.\"
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.\"
.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
.Sh SYNOPSIS
.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
.Fn pathbuf_destroy "struct pathbuf *path"
.Sh DESCRIPTION
The
.Nm
interface is used to carry around pathnames.
This helps simplify the
.Xr namei 9
interface.
A pathbuf should be thought of as a path name string combined with
whatever flags and metadata are needed to interpret it correctly.
It is an abstract type; the internals are hidden within the
.Xr namei 9
implementation.
.Pp
The
.Fn pathbuf_create
function allocates and initializes a new pathbuf containing a copy of
the path string
.Fa path ,
which should be a kernel pointer.
The return value should be checked for being
.Dv NULL
in case the system is out of memory.
Passing a path name larger than
.Dv PATH_MAX
will cause an assertion failure.
.Pp
The
.Fn pathbuf_copyin
function allocates and initializes a new pathbuf containing a path
string copied from user space with
.Xr copyinstr 9 .
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
.Xr namei 9
loads pointers to memory belonging to the pathbuf into the nameidata
structure, a pathbuf should only be destroyed by the
.Fn namei
caller once all manipulations of the nameidata are complete.
.Pp
Also note that calling
.Fn namei
destroys the contents of the pathbuf.
Do not reuse a pathbuf for a second call to
.Fn namei .
.Sh CODE REFERENCES
The
.Nm
code is part of the name lookup code in
.Pa sys/kern/vfs_lookup.c .
.Sh SEE ALSO
.Xr namei 9
.Sh BUGS
There are cases where it is necessary to get the path string left
behind after
.Fn namei
has run.
This produces an effect similar to
.Xr realpath 3 .
The interface for doing this is, for the time being, intentionally
undocumented and subject to change.