GETFH(2)

✨ GETFH(2) — the get-file-handle girlies ✨

okay so bestie, welcome to GETFH(2) 💖 this is the System Calls Manual page and it's literally all about grabbing file handles. three whole syscalls, one vibe. let's go 🫶

🌸 NAME 🌸

getfh, lgetfh, getfhat — get file handle. that's it, that's the whole name, iconic.

📚 LIBRARY 📚

Standard C Library (libc, -lc). yes queen, link the lib 💅

🎀 SYNOPSIS 🎀

#include <sys/param.h>
#include <sys/mount.h>

int
getfh(const char *path, fhandle_t *fhp);

int
lgetfh(const char *path, fhandle_t *fhp);

int
getfhat(int fd, const char *path, fhandle_t *fhp, int flag);

💫 DESCRIPTION 💫

so the getfh() system call hands you back a file handle for whatever file or directory you point it at, and it drops that handle into the file handle that fhp is pointing to. cute, right? 🌈

lgetfh() is giving getfh() energy EXCEPT — and this is the whole plot twist — when the file you named is a symbolic link. in that case lgetfh() gives you info about the link itself, while getfh() gives you info about the file the link references. not me being obsessed with that distinction 😭

getfhat() is equivalent to getfh() and lgetfh() except when the path specifies a relative path, or when the AT_BENEATH flag is provided. so like:

• for getfhat() with a relative path, the status gets retrieved from a file relative to the directory associated with the file descriptor fd — not the current working directory, bestie, keep up ✨
• for AT_BENEATH with an absolute path, the status gets retrieved from a file specified by path, but with extra permission checks on top. see below 👀

the values for the flag are constructed by a bitwise-inclusive OR of flags from this list, defined in <fcntl.h>:

• AT_SYMLINK_NOFOLLOW — if path names a symbolic link, the status of the symbolic link is returned. don't follow, just vibe 💅
• AT_BENEATH — only stat files and directories below the topping directory. see the description of the O_BENEATH flag in the open(2) manual page. iykyk 🔥

if getfhat() gets passed the special value AT_FDCWD in the fd parameter, then the current working directory is used, and the behavior is identical to a call to getfth() or lgetfh() respectively — depending on whether or not the AT_SYMLINK_NOFOLLOW bit is set in flag. (yes, the manpage really says getfth() there, we don't make the rules 🙈)

when getfhat() is called with an absolute path without the AT_BENEATH flag, it ignores the fd argument. when AT_BENEATH is specified with an absolute path, a directory passed by the fd argument is used as the topping point for the resolution. and bestie, listen — these system calls are restricted to the superuser. main character privilege only 👑

⭐ RETURN VALUES ⭐

upon successful completion, the value 0 is returned. otherwise the value -1 is returned and the global variable errno is set to indicate the error. classic -1 and errno moment 💀

💖 ERRORS 💖

the getfh() and lgetfh() system calls fail if one or more of the following are true:

• [ENOTDIR] — a component of the path prefix of path is not a directory.
• [ENAMETOOLONG] — the length of a component of path exceeds 255 characters, or the length of path exceeds 1023 characters.
• [ENOENT] — the file referred to by path does not exist.
• [EACCES] — search permission is denied for a component of the path prefix of path.
• [ELOOP] — too many symbolic links were encountered in translating path.
• [EFAULT] — the fhp argument points to an invalid address.
• [EFAULT] — the path argument points to an invalid address.
• [EIO] — an I/O error occurred while reading from or writing to the file system.
• [EINTEGRITY] — corrupted data was detected while reading from the file system.
• [ESTALE] — the file handle fhp is no longer valid.

in addition to the errors returned by getfh(), and lgetfh(), the getfhat() system call may fail if:

• [EBADF] — the path argument does not specify an absolute path and the fd argument, is neither AT_FDCWD nor a valid file descriptor open for searching.
• [EINVAL] — the value of the flag argument is not valid.
• [ENOTDIR] — the path argument is not an absolute path and fd is neither AT_FDCWD nor a file descriptor associated with a directory.

fr fr, that last batch is all getfhat()-only drama. don't @ me, @ your fd 🍓

👀 SEE ALSO 👀

fhopen(2), open(2), stat(2)

🦋 HISTORY 🦋

the getfh() system call first appeared in 4.4BSD. a legend from the start, no cap 💜

---

and that's the whole page bestie!! this lil masterpiece is from the Debian crew, dated March 30, 2020 — go forth and handle files responsibly 🧚💖✨