# pipeio

The file builtins/pipeio.e (not an autoinclude) contains routines for low-level handling of pipes.
These are (currently) used exclusively with system_exec().
See demo\capture_console.exw for an example of use.
Note this is currently Windows-only. At one point that demo worked on Linux with a few minor glitches, but alas now it just hangs.
None of these routines are supported by pwa/p2js.

## constants

PIPEIN | = 1 -- (for stdin)
PIPOUT | = 2 -- (for stdout)
PIPERR | = 3 -- (for stderr)
READ_PIPE | = 1
WRITE_PIPE | = 2
INHERIT_READ | = 1 -- (for create_pipe)
INHERIT_WRITE | = 2 -- (for create_pipe)

## routines

sequence result = | create_pipe(integer inherit=0) -- create pipe inherit: (windows only) set to INHERIT_READ or INHERIT_WRITE (not both) to inherit from the relevant process. On windows, if inherit is zero then the calling process will not be able to intercept the stdin, stdout, or stderr of the child process; it would only be useful if the pipe handle is passed to the child (by some other means) and it reads or writes that explicitly. result: a pair of {read,write} handles referring to the read and write ends of the pipe. Use result[READ_PIPE] and result[WRITE_PIPE], or {r,w} = result, in preference to [1] and [2].
bool bRes = | write_to_pipe(atom hPipe, atom_string x) -- write a string or character to a pipe hPipe: A result[WRITE_PIPE] from create_pipe(). x: a string or single character (8-bit, and_bits(x,#FF) is performed). An error occurs if x is -1. Returns true on success, false on failure.
atom_string res = | read_from_pipe(atom hPipe, hProc) -- read from a pipe hPipe: A result[READ_PIPE] from create_pipe(). hProc: A process handle from system_exec (with bit 8 set). Returns -1 to signify EOF, otherwise a string.
object res = | close_handles(object p) -- close pipes and/or other handles p: A pipe or other handle, or (nested) sequence of such. res is the same shape as p but composed entirely of NULLs If p or any of its elements are NULL on the way in, nothing happens, in regard to that specific element. Using statements such as pipes[PIPEIN][WRITE_PIPE] = close_handles(pipes[PIPEIN][WRITE_PIPE]) or pipes = close_handles(pipes) helps to ensure we do not accidentally keep references to any closed and/or subsequently re-used handles.

Note the following windows-only constants and routines are not properly documented, and will remain so until they also work on Linux (see/test popen(), fread(), pclose(), in builtins\pfileio.e):
PIPE_TYPE_BYTE, PIPE_TYPE_MESSAGE, PIPE_READMODE_BYTE, PIPE_READMODE_MESSAGE, PIPE_WAIT, PIPE_NOWAIT, PIPE_ACCEPT_REMOTE_CLIENTS, PIPE_REJECT_REMOTE_CLIENTS, PIPE_UNLIMITED_INSTANCES, PIPE_ACCESS_DUPLEX, PIPE_ACCESS_INBOUND, PIPE_ACCESS_OUTBOUND, NMPWAIT_NOWAIT, NMPWAIT_WAIT_FOREVER, NMPWAIT_USE_DEFAULT_WAIT
create_named_pipe(), connect_named_pipe(), close_handle(), disconnect_pipe(), flush_pipe(), read_pipe(), write_pipe(), call_named_pipe() [four or five of those may deserve "named_" in their names].