---
name: "posix_spawn_file_actions_addchdir"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/posix_spawn_file_actions_addchdir"
---

# posix\_spawn\_file\_actions\_addchdir(3)

add open, dup2, close, closefrom, or chdir/fchdir actions to spawn file actions object

## 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**, **posix\_spawn\_file\_actions\_addfchdir** – add open, dup2, close, closefrom, or chdir/fchdir actions to spawn file actions object

## LIBRARY

Standard C Library (libc, -lc)

## 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**(*posix\_spawn\_file\_actions\_t \*restrict file\_actions*, *const char \*restrict path*);

*int*\

**posix\_spawn\_file\_actions\_addfchdir**(*posix\_spawn\_file\_actions\_t \* file\_actions*, *int fildes*);

## DESCRIPTION

These functions add an open, dup2 or close action to a spawn file actions object.

A spawn file actions object is of type *posix\_spawn\_file\_actions\_t* (defined in ⟨spawn.h⟩) and is used to specify a series of actions to be performed by a **posix\_spawn**() or **posix\_spawnp**() operation in order to arrive at the set of open file descriptors for the child process given the set of open file descriptors of the parent.

A spawn file actions object, when passed to **posix\_spawn**() or **posix\_spawnp**(), specify how the set of open file descriptors in the calling process is transformed into a set of potentially open file descriptors for the spawned process. This 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; additionally, when the new process image is executed, any file descriptor (from this new set) which has its FD\_CLOEXEC flag set is closed (see **posix\_spawn**()).

The **posix\_spawn\_file\_actions\_addopen**() function adds an open action to the object referenced by *file\_actions* that causes the file named by *path* to be 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. If *fildes* was already an open file descriptor, it is closed before the new file is opened.

The string described by *path* is copied by the **posix\_spawn\_file\_actions\_addopen**() function.

The **posix\_spawn\_file\_actions\_adddup2**() function adds a dup2 action to the object referenced by *file\_actions* that causes the file descriptor *fildes* to be 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*. The difference from **dup2**() is useful for passing a particular file descriptor to a particular child process.

The **posix\_spawn\_file\_actions\_addclose**() function adds a close action to the object referenced by *file\_actions* that causes the file descriptor *fildes* to be closed (as if

```
close(fildes)
```

had been called) when a new process is spawned using this file actions object.

The **posix\_spawn\_file\_actions\_addclosefrom\_np**() function adds a close action to close all file descriptors numerically equal or greater then the argument *from*. For each open file descriptor, logically the close action is performed, and any possible errors encountered are ignored.

The **posix\_spawn\_file\_actions\_addchdir**() and **posix\_spawn\_file\_actions\_addfchdir**() functions add a change current directory action to the object referenced by *file\_actions* that 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**() function takes the *path* to set as the working directory, while **posix\_spawn\_file\_actions\_addfchdir**() takes the directory file descriptor.

## RETURN VALUES

Upon successful completion, these functions return zero; otherwise, an error number is returned to indicate the error.

## ERRORS

These functions fail if:

- \[EBADF\]

  The value specified by *fildes* or *newfildes* is negative.

- \[ENOMEM\]

  Insufficient memory exists to add to the spawn file actions object.

## SEE ALSO

[close(2)](/close/2.md), [dup2(2)](/dup2/2.md), [open(2)](/open/2.md), [posix\_spawn(3)](/posix_spawn/3.md), [posix\_spawn\_file\_actions\_destroy(3)](/posix_spawn_file_actions_destroy/3.md), [posix\_spawn\_file\_actions\_init(3)](/posix_spawn_file_actions_init/3.md), [posix\_spawnp(3)](/posix_spawnp/3.md)

## 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.

The **posix\_spawn\_file\_actions\_addclosefrom\_np**() function is non-standard and implemented after the similar functionality provided by glibc.

## 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. In FreeBSD 16.0, the **posix\_spawn\_file\_actions\_addchdir**(), **posix\_spawn\_file\_actions\_addfchdir**() aliases where added to the corresponding functions with the ‘\_np’ suffix.

## AUTHORS

Ed Schouten ⟨*ed@FreeBSD.org*⟩