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
Thepathbuf 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
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.