Help:Ctrtool/set_fds

ctrtool set_fds rearranges the file descriptor table in the current process, such that the first specified descriptor is FD 3, second is FD 4, etc. All other file descriptors are closed.

ctrtool set_fds [-s] [{-e|-f} {FD number for 3}[,{FD number for 4}[,...]]] [PROGRAM] [ARGUMENTS]

If -e is specified, FD numbers can be instead /ENV or :ENV, where ENV is an environment variable name and its associated value is a single number. With the /ENV form, ENV is preserved. With the :ENV form, ENV is cleared in the PROGRAM. If -f is specified, /ENV and :ENV are not allowed.

If neither -e nor -f is specified, then all file descriptors >= 3 are closed.

If -s is specified, set LISTEN_PID to the current PID and LISTEN_FDS to the number of file descriptors. This feature is intended to be compatible with the systemd socket activation feature found in many modern server applications.

Example

Before ctrtool set_fds:

File descriptor number Referred object
0 /dev/pts/0
1 pipe:[123456]
2 /dev/pts/0
3 socket:[123457]
4 socket:[222333]
5 socket:[222444]
10 /dev/ptmx
11 /dev/null
12 /dev/pts/1

After ctrtool set_fds -f 4,1,3,3,11,10:

File descriptor number Referred object
0 /dev/pts/0
1 pipe:[123456]
2 /dev/pts/0
3 socket:[222333] (originally FD 4)
4 pipe:[123456] (originally FD 1)
5 socket:[123457] (originally FD 3)
6 socket:[123457] (originally FD 3, same as the new FD 5)
7 /dev/null (originally FD 11)
8 /dev/ptmx (originally FD 10)

All file descriptor numbers > 8 are closed.

Bugs

  • -e and -f can only be specified once.
  • The close_range() syscall is used if possible, otherwise (only if it fails with ENOSYS) it falls back to scanning /proc/self/fd. This may be problematic if a seccomp filter causes close_range to return a different value for errno, such as EPERM or EINVAL.
  • There should also be a means to specify target file descriptors less than 3.
This end-user documentation is part of ctrtool. Reproduction and use of this material for any purpose is permitted, provided that a link to this page is provided as attribution.