Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

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.

NetBSD 10.99                   November 30, 2010                  NetBSD 10.99