FHOPEN(2)

📦 version 12.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 FHOPEN(2) 💖

okay bestie, gather round, because today we're talking about fhopen, fhstat, and fhstatfs — the trio that lets you access a file via file handle. yes, via file handle. not via path. it's giving backdoor-but-make-it-official energy and honestly? iconic. 👑

✨ LIBRARY ✨

Standard C Library (libc, -lc) — you know her, you love her, she's already linked in. 💅

✨ SYNOPSIS ✨

so first you gotta invite the whole squad in:

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

then, the moment you've been waiting for:

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);

three little functions, three little glow-ups. 🦋

✨ DESCRIPTION ✨

okay so here's the tea. these system calls are your way to reach a file when all you've got is the file handle fhp. and the way that this bypasses directory access restrictions?? yeah. that's exactly why these calls are restricted to the superuser. no cap, you need root for this one. it's VIP-only, the bouncer does NOT care how cute your outfit is. 🚫✨

The fhopen() system call opens the file referenced by fhp for reading and/or writing as specified by the argument flags, and hands the file descriptor back to the calling process. the flags argument is specified by or'ing together the flags used for the open(2) system call. all said flags are valid except for O_CREAT — that one's a hard no, sorry babe. 😭

The fhstat() and fhstatfs() system calls provide the functionality of the fstat(2) and fstatfs(2) calls, except that they return information for the file referred to by fhp rather than an open file. same vibe, different source of truth. 💜

✨ 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. slay when it works, sob when it doesn't. 🫶

The fhstat() and fhstatfs() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. classic.

✨ 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. bestie we TOLD you, O_CREAT is not invited to this party. 💀
  • [ESTALE] — The file handle fhp is no longer valid. it's giving expired group chat invite. it's over, it's stale, let it go. 🙈

✨ SEE ALSO ✨

go read the extended universe, it's all connected:

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. a glow-up arc across two BSDs, we love to see it. ⭐

✨ AUTHORS ✨

This manual page was written by William Studenmund for NetBSD. king behavior, honestly. 👑

🌸 and that's the whole page, bestie! this little beauty comes to you from Debian, dated June 29, 1999 — yeah she's a vintage queen and she still ate. go forth and fhopen responsibly (with root, obviously). mwah! 💖✨🎀

📦 where this page comes from