fspick(2)

💅 fspick(2) — the girlies' guide to picking a filesystem for reconfiguration

Okay so bestie, gather round, because we're talking about fspick(2), a real one from the Linux System Calls Manual. It lives in the Standard C library (libc, -lc) and it's lowkey iconic. 🦋

---

✨ NAME ✨

fspick — select filesystem for reconfiguration

---

📚 LIBRARY 📚

Standard C library (libc, -lc)

---

🎀 SYNOPSIS 🎀

#include <fcntl.h>          /* Definition of AT_* constants */
#include <sys/mount.h>

int fspick(int dirfd, const char *path, unsigned int flags);

---

🌸 DESCRIPTION 🌸

So fspick() is part of the whole suite of file-descriptor-based mount facilities in Linux — the cool kids' table, if you will. 👑

What it does: fspick() creates a new filesystem configuration context for the extant filesystem instance associated with the path described by dirfd and path, and it drops that context straight into reconfiguration mode (basically the same energy as mount(8) with the -o remount option). Then it hands you back a brand-new file descriptor attached to that filesystem configuration context. ✨

Heads up though: the calling process must have the CAP_SYS_ADMIN capability in order to create a new filesystem configuration context. No cap, no context, no vibes. 💀

Once you have that file descriptor, you can use it with fsconfig(2) to specify the exact set of changes you want made to the filesystem parameters of that filesystem instance. And once the desired set of changes have been configured, you can actually effectuate them by calling fsconfig(2) with the FSCONFIG_CMD_RECONFIGURE command. Periodt. 💅

Not me explaining the glow-up here: in contrast to the behavior of MS_REMOUNT with mount(2), fspick() instantiates the filesystem configuration context with a copy of the extant filesystem's filesystem parameters. So subsequent FSCONFIG_CMD_RECONFIGURE operations will only update the filesystem parameters you explicitly modified with fsconfig(2). Everyone else stays untouched, minding their own business. 🫶

🧚 How dirfd + path actually work together 🧚

As with *at() system calls, fspick() uses the dirfd argument in conjunction with the path argument to determine the path to operate on, as follows:

• If the pathname given in path is absolute, then dirfd is ignored. (She said what she said.)
• If the pathname given in path is relative and dirfd is the special value AT_FDCWD, then path is interpreted relative to the current working directory of the calling process (like open(2)).
• If the pathname given in path is relative, then it is interpreted relative to the directory referred to by the file descriptor dirfd (rather than relative to the current working directory of the calling process, as is done by open(2) for a relative pathname). In this case, dirfd must be a directory that was opened for reading (O_RDONLY) or using the O_PATH flag.
• If path is an empty string, and flags contains FSPICK_EMPTY_PATH, then the file descriptor dirfd is operated on directly. In this case, dirfd may refer to any type of file, not just a directory. 🌈

See openat(2) for an explanation of why the dirfd argument is useful.

---

🌟 the flags, bestie 🌟

flags can be used to control aspects of how path is resolved and properties of the returned file descriptor. A value for flags is constructed by bitwise ORing zero or more of the following constants:

• FSPICK_CLOEXEC — Set the close-on-exec (FD_CLOEXEC) flag on the new file descriptor. See the description of the O_CLOEXEC flag in open(2) for reasons why this may be useful. (Spoiler: it's the "don't leak me into my children" flag. Responsible queen behavior. 💖)
• FSPICK_EMPTY_PATH — If path is an empty string, operate on the file referred to by dirfd (which may have been obtained from open(2), fsmount(2), or open_tree(2)). In this case, dirfd may refer to any type of file, not just a directory. If dirfd is AT_FDCWD, fspick() will operate on the current working directory of the calling process.
• FSPICK_SYMLINK_NOFOLLOW — Do not follow symbolic links in the terminal component of path. If path references a symbolic link, the returned filesystem context will reference the filesystem that the symbolic link itself resides on. (We're staying on this side of the link, thank you. 🚫🔗)
• FSPICK_NO_AUTOMOUNT — Do not automount the terminal ("basename") component of path if it is a directory that is an automount point. This allows you to reconfigure an automount point, rather than the location that would be mounted. This flag has no effect if the automount point has already been mounted over.

📬 message retrieval, iykyk 📬

As with filesystem contexts created with fsopen(2), the file descriptor returned by fspick() may be queried for message strings at any time by calling read(2) on the file descriptor. (See the "Message retrieval interface" subsection in fsopen(2) for more details on the message format.)

---

🔥 RETURN VALUE 🔥

On success, a new file descriptor is returned. 🎉

On error, -1 is returned, and errno is set to indicate the error. 😭

---

💀 ERRORS 💀

• EACCES — Search permission is denied for one of the directories in the path prefix of path. (See also path_resolution(7).)
• EBADF — path is relative but dirfd is neither AT_FDCWD nor a valid file descriptor.
• EFAULT — path is NULL or a pointer to a location outside the calling process's accessible address space.
• EINVAL — Invalid flag specified in flags.
• ELOOP — Too many symbolic links encountered when resolving path.
• EMFILE — The calling process has too many open files to create more.
• ENAMETOOLONG — path is longer than PATH_MAX.
• ENFILE — The system has too many open files to create more.
• ENOENT — A component of path does not exist, or is a dangling symbolic link.
• ENOENT — path is an empty string, but FSPICK_EMPTY_PATH is not specified in flags. (Yes she's listed twice, they're different crimes, don't @ me. 🙈)
• ENOTDIR — A component of the path prefix of path is not a directory; or path is relative and dirfd is a file descriptor referring to a file other than a directory.
• ENOMEM — The kernel could not allocate sufficient memory to complete the operation.
• EPERM — The calling process does not have the required CAP_SYS_ADMIN capability.

---

👑 STANDARDS 👑

Linux. That's it, that's the standard.

---

🕰️ HISTORY 🕰️

Linux 5.2. glibc 2.36.

---

🍓 EXAMPLES 🍓

The following example sets the read-only flag on the filesystem instance referenced by the mount object attached at /tmp.

int fsfd = fspick(AT_FDCWD, "/tmp", FSPICK_CLOEXEC);
fsconfig(fsfd, FSCONFIG_SET_FLAG, "ro", NULL, 0);
fsconfig(fsfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);

The above procedure is roughly equivalent to the following mount operation using mount(2):

mount(NULL, "/tmp", NULL, MS_REMOUNT | MS_RDONLY, NULL);

With the notable caveat that in this example, mount(2) will clear all other filesystem parameters (such as MS_DIRSYNC or MS_SYNCHRONOUS); fsconfig(2) will only modify the ro parameter. So like… one of these is a glow-up and one of these is a makeover gone wrong. Choose wisely. ⭐

---

🫶 SEE ALSO 🫶

fsconfig(2), fsmount(2), fsopen(2), mount(2), mount_setattr(2), move_mount(2), open_tree(2), mount_namespaces(7)

---

and that's the whole page, bestie 💖 brought to you by Linux man-pages 6.20, dated 2025-12-25 — yes, a Christmas Day release, the devs really said "gift for the girlies" 🎁✨ go forth and remount responsibly, mwah 💅🌸