pipe 1 user commands nosh
pipe execute two commands with a pipe between them
`pipe` --inwards --error --grandchild --ignore-children --separator alt-sep left-prog | right-prog

## Description

`pipe` is a chain-loading utility that opens a pipe with the pipe 2 library function, and runs left-prog with its standard output writing to the pipe and right-prog with its standard input reading from the pipe. It chain loads one of the twain and runs the other as a child process created by fork 3. Both are executed with the execvp 3 function.

left-prog and right-prog may contain their own command line options, which `pipe` will ignore.

Normally, in outwards mode, left-prog is chain loaded in the original process and right-prog is forked and run in the new child process. If the --inwards command line option is used, right-prog is chain loaded in the original process and left-prog is forked and run in the new child process.

The --separator command line option specifies an alternative separator argument, to scan for in place of |.

The --grandchild command line option causes whichever side of the pipe that is run in the forked child to perform a second fork and then exit, so that that side of the pipe runs in an orphaned child process. This is useful when it is known that the side of the pipe that runs in the forked parent never cleans up its terminated children. However, it makes the process tree less obvious. An alternative to this is the --ignore-children command line option which makes the parent program ignore the `SIGCHLD` signal.

## Usage

The primary use of `pipe` is from a nosh 1 script to enact a pipeline. When invoking `pipe` from within a shell script, remember that | must be escaped or quoted in order to prevent the shell from recognizing it.

`pipe` looks for the leftmost instance of |, and separates left from right there. Further instances of | in right-prog are left alone. This allows longer pipelines, by using another `pipe` in right-prog. For example: `pipe cat head body foot | pipe sort | uniq`

Piping both standard error and standard output is done as it would be in a shell: by an explicit redirection in left-prog, using fdmove 1 or a similar utility. (In the shell, the explicit redirection would be `2>&1`.) For example: `pipe fdmove -c 2 1 wibble | less` Remember that the redirection must be enacted within left-prog. `fdmove -c 2 1 pipe wibble | less` would redirect the standard error of the entire pipeline.

## Author

Jonathan de Boyne Pollard