HANDLE(3)

💖 HANDLE(3) — file handle operations 💖

okay so bestie, welcome to the Library Functions Manual, section 3 (that's the C library functions girlies, not the syscall girlies, not the admin girls — we're in library functions territory). this whole page is about ✨ handles ✨ and it's genuinely iconic, let's get into it.

🌸 NAME 🌸

path_to_handle, path_to_fshandle, fd_to_handle, handle_to_fshandle, open_by_handle, readlink_by_handle, attr_multi_by_handle, attr_list_by_handle, fssetdm_by_handle, free_handle, getparents_by_handle, getparentpaths_by_handle — file handle operations 🫶

🎀 C SYNOPSIS 🎀

#include <sys/types.h>
#include <xfs/handle.h>

int path_to_handle(char *path, void **hanp, size_t *hlen);

int path_to_fshandle(char *path, void **hanp, size_t *hlen);

int fd_to_handle(int fd, void **hanp, size_t *hlen);

int handle_to_fshandle(void *hanp, size_t hlen, void **fshanp, size_t
       *fshlen);

int open_by_handle(void *hanp, size_t hlen, int oflag);

int readlink_by_handle(void *hanp, size_t hlen, void *buf, size_t bs);

int attr_multi_by_handle(void *hanp, size_t hlen, void *buf, int
       rtrvcnt, int flags);

int attr_list_by_handle(void *hanp, size_t hlen, char *buf, size_t
       bufsiz, int flags, struct attrlist_cursor *cursor);

int fssetdm_by_handle(void *hanp, size_t hlen, struct fsdmidata
       *fssetdm);

void free_handle(void *hanp, size_t hlen);

int getparents_by_handle(void *hanp, size_t hlen, parent_t *buf, size_t
       bufsiz, parent_cursor_t *cursor, unsigned int *count, unsigned
       int *more);

int getparentpaths_by_handle(void *hanp, size_t hlen, parent_t *buf,
       size_t bufsiz, parent_cursor_t *cursor, unsigned int *count,
       unsigned int *more);

look at that list. twelve functions. no cap. 💅

✨ DESCRIPTION ✨

so these functions let you do certain filesystem operations without needing a file descriptor to get at filesystem objects. it's giving "i don't have an fd but i still need answers." they're meant for a limited set of system utilities — backup programs and that kind of thing, the girlies who need to reach objects directly. and heads up: they are supported only by the XFS filesystem. to actually use these, you link with the libhandle library. 🦋

a handle, hanp, uniquely identifies a filesystem object or an entire filesystem. there is one and only one handle per filesystem or filesystem object — monogamy, periodt. handles consist of some number of bytes. the size of a handle (i.e. the number of bytes comprising it) varies by the type of handle and may vary for different objects of the same type. the content of a handle is opaque to applications, meaning you don't get to peek, that's not your business 🙈. since handle sizes vary and their contents are opaque, handles are described by two quantities: a pointer (hanp) and a size (hlen). the size, hlen, tells you the number of bytes in the handle which are pointed to by the pointer. dynamic sizing, we love to see it. 💖

here's the function-by-function tea:

• path_to_handle() — returns the handle for the object given by the path argument. and bestie, important detail: if the final component of the path name is a symbolic link, the handle returned is that of the link itself 👀 (not what it points to, the link, the link).
• path_to_fshandle() — returns the handle for the filesystem in which the object given by the path argument resides.
• fd_to_handle() — returns the handle for the object referenced by the fd argument, which must be a valid file descriptor.
• handle_to_fshandle() — returns the handle for the filesystem in which the object referenced by the handle given by the hanp and hlen arguments resides.
• open_by_handle() — opens a file descriptor for the object referenced by a handle. it's analogous and identical to open(2), with the one exception that it accepts handles instead of path names. glow up.
• readlink_by_handle() — returns the contents of a symbolic link referenced by a handle.
• attr_multi_by_handle() — manipulates multiple user attributes on a filesystem object. analogous and identical to attr_multif(3) except that a handle is specified instead of a file descriptor.
• attr_list_by_handle() — returns the names of the user attributes of a filesystem object. analogous and identical to attr_listf(3) except that a handle is specified instead of a file descriptor.
• fssetdm_by_handle() — sets the di_dmevmask and di_dmstate fields in an XFS on-disk inode. it's analogous to the XFS_IOC_FSSETDM xfsctl(3) command, except that a handle is specified instead of a file. > ⚠️ this function is not supported on Linux. sorry babe.
• free_handle() — frees the storage allocated for handles returned by the following functions: path_to_handle(), path_to_fshandle(), fd_to_handle(), and handle_to_fshandle(). clean up after yourself, be a good citizen 🧚
• getparents_by_handle() — returns an array of parent_t structures for each hardlink to the inode represented by the given handle. the parent structure encodes the parent inode number, generation number and the basename of the link. > ⚠️ this function is not operational on Linux.
• getparentpaths_by_handle() — identical to the getparents_by_handle() function except that instead of returning the basename it returns the path of the link up to the mount point. > ⚠️ this function is also not operational on Linux.

🌈 RETURN VALUE 🌈

free_handle() has no failure indication — it just vibes, it can't fail at you. the other functions return the value 0 to the calling process if they succeed; otherwise they return the value -1 and set errno to indicate the error. classic zero-or-minus-one situation, iykyk.

💀 ERRORS 💀

• EACCES — search permission was denied for a component of path.
• EBADF — fd is not a valid and open file descriptor.
• EFAULT — an argument pointed to an invalid address.
• EINVAL — path is in a filesystem that does not support these functions.
• ELOOP — too many symbolic links were encountered in translating the path name.
• ENAMETOOLONG — a component of path or the entire length of path exceeds filesystem limits.
• ENOENT — a component of path does not exist.
• EPERM — the caller does not have sufficient privileges.

👑 SEE ALSO 👑

open(2), readlink(2), attr_multi(3), attr_list(3), xfsctl(3), xfs(5).

and that's the whole page bestie, go forth and handle responsibly 🫶💅✨

this has been HANDLE(3), page three of the Library Functions Manual — mwah, you ate that reading session, no crumbs left 🎀💖