NAME
pathbuf,
pathbuf_create,
pathbuf_assimilate,
pathbuf_copyin,
pathbuf_destroy —
path buffer
abstraction
SYNOPSIS
#include <sys/namei.h>
struct pathbuf *
pathbuf_create(
const
char *path);
struct pathbuf *
pathbuf_assimilate(
char
*pnbuf);
int
pathbuf_copyin(
const
char *userpath,
struct
pathbuf **ret);
void
pathbuf_destroy(
struct
pathbuf *path);
DESCRIPTION
The
pathbuf interface is used to carry around pathnames. This
helps simplify the
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
namei(9) implementation.
The
pathbuf_create() function allocates and initializes a new
pathbuf containing a copy of the path string
path, which
should be a kernel pointer. The return value should be checked for being
NULL
in case the system is out of memory. Passing a
path name larger than
PATH_MAX
will cause an assertion
failure.
The
pathbuf_copyin() function allocates and initializes a new
pathbuf containing a path string copied from user space with
copyinstr(9). It returns an
error code.
The
pathbuf_assimilate() function creates a pathbuf using the
string buffer provided as
pnbuf. This buffer must be of
size
PATH_MAX
and must have been allocated with
PNBUF_GET(). The buffer is “taken over” by the
returned pathbuf and will be released when the pathbuf is destroyed. Note: to
avoid confusion and pointer bugs,
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.
The
pathbuf_destroy() function deallocates a pathbuf. Caution:
because calling
namei(9) loads
pointers to memory belonging to the pathbuf into the nameidata structure, a
pathbuf should only be destroyed by the
namei() caller once
all manipulations of the nameidata are complete.
Also note that calling
namei() destroys the contents of the
pathbuf. Do not reuse a pathbuf for a second call to
namei().
CODE REFERENCES
The
pathbuf code is part of the name lookup code in
sys/kern/vfs_lookup.c.
SEE ALSO
namei(9)
BUGS
There are cases where it is necessary to get the path string left behind after
namei() has run. This produces an effect similar to
realpath(3). The interface for
doing this is, for the time being, intentionally undocumented and subject to
change.