PATHBUF(9)

okay so bestie, welcome to the PATHBUF(9) page from the Kernel Developer's Manual 🫶✨ this one is lowkey iconic.

💖 NAME 💖

pathbuf, pathbuf_create, pathbuf_assimilate, pathbuf_copyin, pathbuf_destroy — path buffer abstraction. periodt 💅

🌸 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 🦋

okay so the pathbuf interface is used to carry around pathnames, and it 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 👀

• pathbuf_create() — allocates and initializes a new pathbuf containing a copy of the path string path, which should be a kernel pointer. Check the return value for being NULL in case the system is out of memory 😭. Passing a path name larger than PATH_MAX will cause an assertion failure — so do not do that bestie 💀
• pathbuf_copyin() — allocates and initializes a new pathbuf containing a path string copied from user space with copyinstr(9). It returns an error code.
• pathbuf_assimilate() — 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.

• pathbuf_destroy() — 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 — it’s giving mystery on purpose 😭✨

okay bye bestie — this page is from Debian, dated November 30, 2010 💖🫶