POSIX_SPAWN_FILE_ACTIONS_ADDFCHDIR_NP(3)

🌸 POSIX_SPAWN_FILE_ACTIONS(3) 🌸

okay bestie, this is the <spawn.h> family of file-actions adders — the whole girl squad that piles open/dup2/close/closefrom/chdir/fchdir actions onto a spawn file actions object so your tiny child process gets its fds exactly right. Standard C Library (libc, -lc), and yes, we have six of them. Buckle up. 💅

---

✨ NAME ✨

posix_spawn_file_actions_addopen, posix_spawn_file_actions_adddup2, posix_spawn_file_actions_addclose, posix_spawn_file_actions_addclosefrom_np, posix_spawn_file_actions_addchdir_np, posix_spawn_file_actions_addfchdir_np — they add open, dup2, close, closefrom, or chdir/fchdir actions to a spawn file actions object. That's the whole job. Iconic behavior, honestly.

---

🫶 LIBRARY 🫶

Standard C Library (libc, -lc) — she lives with the rest of the libc girlies, no extra linking drama.

---

🎀 SYNOPSIS 🎀

#include <spawn.h>

int
posix_spawn_file_actions_addopen(posix_spawn_file_actions_t * file_actions,
    int fildes, const char *restrict path, int oflag, mode_t mode);

int
posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t * file_actions,
    int fildes, int newfildes);

int
posix_spawn_file_actions_addclose(posix_spawn_file_actions_t * file_actions,
    int fildes);

int
posix_spawn_file_actions_addclosefrom_np(posix_spawn_file_actions_t * file_actions,
    int from);

int
posix_spawn_file_actions_addchdir_np(posix_spawn_file_actions_t *restrict file_actions,
    const char *restrict path);

int
posix_spawn_file_actions_addfchdir_np(posix_spawn_file_actions_t * file_actions,
    int fildes);

---

🦋 DESCRIPTION 🦋

So these functions add an open, dup2, or close action to a spawn file actions object. Simple concept, lots of little moments. 💖

A spawn file actions object is of type posix_spawn_file_actions_t (defined in <spawn.h>), and honestly its whole personality is: it holds a series of actions that a posix_spawn() or posix_spawnp() operation performs so the child process ends up with the right set of open file descriptors, given the parent's set. It's basically a glow-up plan for fds. ✨

When you pass a spawn file actions object to posix_spawn() or posix_spawnp(), it specifies how the set of open file descriptors in the calling process gets transformed into a set of potentially open file descriptors for the spawned process. The transformation is as if the specified sequence of actions was performed exactly once, in the context of the spawned process (prior to execution of the new process image), in the order in which the actions were added to the object. And on top of that — when the new process image is executed, any file descriptor (from this new set) that has its FD_CLOEXEC flag set is closed (see posix_spawn()). No cap. 👑

🌸 the open one

The posix_spawn_file_actions_addopen() function adds an open action to the object referenced by file_actions. It makes the file named by path get opened (as if

open(path, oflag, mode)

had been called, and the returned file descriptor, if not fildes, had been changed to fildes) when a new process is spawned using this file actions object. And heads up: if fildes was already an open file descriptor, it gets closed before the new file is opened. Clean slate energy. 💅

The string described by path is copied by the posix_spawn_file_actions_addopen() function. Your string is safe, she took a copy, bestie. 🫶

💜 the dup2 one

The posix_spawn_file_actions_adddup2() function adds a dup2 action to the object referenced by file_actions. It makes file descriptor fildes get duplicated as newfildes (as if

dup2(fildes, newfildes)

had been called) when a new process is spawned using this file actions object — except that the FD_CLOEXEC flag for newfildes is cleared even if fildes is equal to newfildes. That little difference from dup2() is genuinely useful for passing a particular file descriptor to a particular child process. iykyk. 🔥

🌈 the close one

The posix_spawn_file_actions_addclose() function adds a close action to the object referenced by file_actions. It makes file descriptor fildes get closed (as if

close(fildes)

had been called) when a new process is spawned using this file actions object. Bye-bye fd, slay. 👋

⭐ the closefrom one (non-standard, fancy)

The posix_spawn_file_actions_addclosefrom_np() function adds a close action to close all file descriptors numerically equal or greater than the argument from. For each open file descriptor, logically the close action is performed, and any possible errors encountered are ignored. Yes — ignored. She does not care, she does not read the replies. 💀

🧚 the chdir / fchdir ones

The posix_spawn_file_actions_addchdir_np() and posix_spawn_file_actions_addfchdir_np() functions add a change-current-directory action to the object referenced by file_actions. It affects actions (opens with relative path) performed after the operation, in the order of insertion into the file_actions object. It also sets the working directory for the spawned program. The posix_spawn_file_actions_addchdir_np() function takes the path to set as the working directory, while posix_spawn_file_actions_addfchdir_np() takes the directory file descriptor. Two ways to say "we're moving, bestie." 📦✨

---

🍓 RETURN VALUES 🍓

Upon successful completion, these functions return zero; otherwise, an error number is returned to indicate the error. Zero = we ate. Anything else = check the ERRORS section below, diva. 💖

---

🙈 ERRORS 🙈

These functions fail if:

• [EBADF] — The value specified by fildes or newfildes is negative. Negative fd? In this economy? No. 🚫
• [ENOMEM] — Insufficient memory exists to add to the spawn file actions object. The actions object said "I'm full, babe." 😭

---

🔥 SEE ALSO 🔥

close(2), dup2(2), open(2), posix_spawn(3), posix_spawn_file_actions_destroy(3), posix_spawn_file_actions_init(3), posix_spawnp(3) — go read the whole squad, they're all linked. The crossover episode. 🌟

---

👑 STANDARDS 👑

The posix_spawn_file_actions_addopen(), posix_spawn_file_actions_adddup2() and posix_spawn_file_actions_addclose() functions conform to IEEE Std 1003.1-2001 ("POSIX.1"), with the exception of the behavior of posix_spawn_file_actions_adddup2() if fildes is equal to newfildes (clearing FD_CLOEXEC). A future update of the Standard is expected to require this behavior. So like — we're ahead of the curve, ngl. 💅

The posix_spawn_file_actions_addchdir_np(), posix_spawn_file_actions_addfchdir_np(), and posix_spawn_file_actions_addclosefrom_np() functions are non-standard functions implemented after the similar functionality provided by glibc. The _np at the end literally means non-portable, so don't come for me if you take these to another OS and they don't exist. 😭

---

🌸 HISTORY 🌸

The posix_spawn_file_actions_addopen(), posix_spawn_file_actions_adddup2() and posix_spawn_file_actions_addclose() functions first appeared in FreeBSD 8.0. The posix_spawn_file_actions_addchdir_np(), posix_spawn_file_actions_addfchdir_np(), and posix_spawn_file_actions_addclosefrom_np() functions first appeared in FreeBSD 13.1. Literal glow-up timeline. ⏳✨

---

💜 AUTHORS 💜

Ed Schouten <ed@FreeBSD.org> — king behavior, we stan. 🫶👑

---

okay that's the whole page bestie, go forth and spawn responsibly 🦋

— Debian, May 9 · page POSIX_SPAWN_FILE_ACTIONS_ADDOPEN(3) · you've reached the end, mwah 💋