local-stream-socket-connect 1 user commands nosh
local-stream-socket-connect connect a socket to a local stream socket server and chain
`local-stream-socket-connect` --verbose --local-path client-path server-path next-prog

## Description

`local-stream-socket-connect` is a chain-loading utility that opens a local stream socket, connects it to server-path with connect 3, and then chain loads to next-prog with the execvp 3 function, having set up I/O and environment variables per the UCSPI conventions.

next-prog may contain its own command line options, which `local-stream-socket-connect` will ignore.

If the --verbose option is used, `local-stream-socket-connect` logs information about connections made.

### UCSPI (specifically UCSPI-UNIX) conventions

next-prog is expected to follow the UCSPI conventions: standard input, output, and error are the same as whatever `local-stream-socket-connect` inherited; file descriptors 6 and 7 are (respectively) reading from and writing to the connected socket, which it should treat as generic I/O streams and not expect to be a socket; and information about the local and remote ends of the connected socket is in environment variables. Whatever `local-stream-socket-connect` itself inherited as file descriptors 6 and 7 is closed.

`local-stream-socket-connect` obtains information about the local socket connection using the `getpeername` 2, `getsockname` 2, and (if available) `SO_PEERCRED` option of the `getsockopt` 2 library functions, and sets up the UCSPI-UNIX conventional environment variables as follows:

`PROTO`

  This always has the value `UNIX`, indicating the prefix to the names of the remaining environment variables.

`UNIXLOCALPATH`

  The local (client) path of the connecting socket. Normally, the operating system assigns this; but an explicit assignment can be requested with the --local-path command-line option, where client-path is a pathname.

`UNIXREMOTEPATH`

  The remote (server) path of the connected socket, in human-readable form.

`UNIXREMOTEPID`

  The PID of the remote (server) process.

`UNIXREMOTEEUID`

  The effective UID of the remote (server) process.

`UNIXREMOTEEGID`

  The effective GID of the remote (server) process.

## Author

Jonathan de Boyne Pollard