fifo-listen 1 user commands nosh
fifo-listen open the read end of a FIFO and chain
`fifo-listen` --uid number --gid number --mode number --systemd-compatibility path next-prog

## Description

`fifo-listen` is a chain-loading utility that opens the read end of the FIFO at path, sets the FIFO to file descriptor 3+n (where n is the number of already-opened listening file descriptors), closing whatever that descriptor was, and then chain loads to next-prog with the execvp 3 function.

next-prog may contain its own command line options, which `fifo-listen` will ignore.

For compatibility with dæmons that expect to be run under inetd 1, inheriting the listening socket as their standard input, simply use `fdmove` 0 3 in next-prog. See fdmove 1.

After opening it, using the permissions specified with the --mode command line argument (if supplied), `fifo-listen` changes the owner UID of the FIFO to that specified with the --uid command line argument (if supplied), and changes the GID of the FIFO to that specified with the --gid command line argument (if supplied). The normal conventions for numbers apply, so for octal permissions use a leading zero. Symbolic permissions and account names are not supported.

The --systemd-compatibility option is for compatibility with dæmons that expect to be run under systemd 1. It causes `fifo-listen` to set the `LISTEN_FDS` environment variable to the number of listening file descriptors, and the `LISTEN_PID` environment variable to its own process ID. If the command is started up with the `LISTEN_FDS` and the `LISTEN_PID` environment variables already appropriately set, the number of listening file descriptors is taken from them and increased by one, otherwise the number of file descriptors is 1. Thus a list of listening file descriptors can be built up with multiple commands, as long as they all use the --systemd-compatibility option.

## Portability

The POSIX standard does not specify that FIFOs can be opened in read-write mode, only specifying that they can be opened in either write-only or read-only modes. Some operating systems, however, provide the ability to open FIFOs in read-write mode as an extension. Doing so has the advantage of not terminating the listening server whenever individual clients disconnect. `fifo-listen` attempts to open the FIFO in read-write mode on such operating systems, using read-only mode on the others.

## Security

`fifo-listen` will successfully open, change ownership of, and change permissions of path even if it is not a FIFO. This is to allow its use with non-FIFO files such as `/dev/kmsg`, `/proc/kmsg`i, and `/dev/klog`.

## Author

Jonathan de Boyne Pollard