FHOPEN(2)

✨ FHOPEN — access file via file handle ✨

okay so bestie, welcome to FHOPEN(2), aka the "I have a file handle and I'm not afraid to use it" page 💅 it's in the System Calls Manual, and it covers three little icons: fhopen, fhstat, and fhstatfs. grab a boba, we're going in 🫶

---

🎀 NAME 🎀

fhopen, fhstat, fhstatfs — literally the trio that lets you access a file via a file handle. that's the whole vibe. no cap. ✨

📚 LIBRARY 📚

Standard C Library (libc, -lc) — yeah she's built in, you're welcome 💖

🦋 SYNOPSIS 🦋

first, manifest the headers into your life:

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

then the actual functions, in all their glory:

int
fhopen(const fhandle_t *fhp, int flags);

int
fhstat(const fhandle_t *fhp, struct stat *sb);

int
fhstatfs(const fhandle_t *fhp, struct statfs *buf);

🌸 DESCRIPTION 🌸

okay so these system calls are your backstage pass — they give you a way to access a file given the file handle fhp. the way that *bypasses directory access restrictions*… 👀 so yeah, that's exactly why these calls are restricted to the superuser. main character energy, but with security guards. periodt.

fhopen() opens the file referenced by fhp for reading and/or writing, as specified by the argument flags, and returns the file descriptor to the calling process. and how do you build that flags? you or'ing together the flags used for the open(2) system call 💅 all said flags are valid except for O_CREAT — do not, I repeat, do NOT bring O_CREAT to this party 🚫 and if the file handle refers to a named attribute or named attribute directory, then the O_NAMEDATTR flag must be specified. it's giving "dress code enforced" 🎀

fhstat() and fhstatfs()? they provide the functionality of the fstat(2) and fstatfs(2) calls — except they return information for the file referred to by fhp rather than an open file. same energy, different source. iconic honestly 💜

---

🔥 RETURN VALUES 🔥

upon successful completion, fhopen() returns the file descriptor for the opened file 🎉 otherwise the value -1 is returned and the global variable errno is set to indicate the error. sad girl hours 😭

the fhstat() and fhstatfs() functions return the value 0 if successful — slay — otherwise the value -1 is returned and the global variable errno is set to indicate the error. lowkey rude but okay 🫠

💀 ERRORS 💀

in addition to the errors returned by open(2), fstat(2), and fstatfs(2) respectively, fhopen(), fhstat(), and fhstatfs() will return:

• [EINVAL] — calling fhopen() with O_CREAT set. we said no 😤
• [ENOATTR] — the file handle does not refer to a named attribute or named attribute directory although the O_NAMEDATTR flag was specified. mismatch era. 🫠
• [ENOATTR] — the file handle does refer to a named attribute or named attribute directory although the O_NAMEDATTR flag was not specified. the other flavour of mismatch, fr fr. 🙈
• [ESTALE] — the file handle fhp is no longer valid. expired. stale. not fresh. 💀

ngl bestie, the two [ENOATTR] entries are not a typo — that's genuinely how the page lists them, one for each direction of the flag/handle mismatch. both count! 💅

👑 SEE ALSO 👑

fstat(2), fstatfs(2), getfh(2), open(2), named_attribute(7) — go read these next, iykyk 📚✨

🧚 HISTORY 🧚

the fhopen(), fhstat(), and fhstatfs() system calls first appeared in NetBSD 1.5 and were adapted to FreeBSD 4.0 by Alfred Perlstein. vintage behaviour, honestly. 🌈

🍓 AUTHORS 🍓

this manual page was written by William Studenmund for NetBSD. king behaviour, we stan 🫶

---

and that's the whole page, bestie! this lil drop is from the Debian build, dated July 20, 2025 — go forth and handle those files responsibly, mwah 💋💖