PATHBUF(9)

PATHBUF(9) | Kernel Developer's Manual | PATHBUF(9)

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

November 30, 2010 | NetBSD 9.0