I/O utilities
=============

These procedures for manipulating pipes and ports built on file descriptors are provided by the structures posix-i/o & posix.

 -- procedure: open-pipe returns [input-port output-port]
     Creates a pipe and returns the two ends of the pipe as an input port & an output port.

A file descriptor port (or fd-port) is a port or a Channels, channel that reads from or writes to an OS file descriptor.  File descriptor ports are returned by the standard Scheme procedures open-input-file & open-output-file as well as the procedures open-file & open-pipe from this POSIX interface.

 -- procedure: fd-port? port returns boolean
 -- procedure: port->fd port returns integer or #f
     Fd-port? returns true if PORT is a port that reads from or writes to a file descriptor, or false if not.  Port->fd returns the file descriptor that PORT reads from or writes to, if it is a file descriptor port, or #f if it is not.  It is an error to pass a value that is not a port to either of these procedures.

     Note: Channels may not be passed to these procedures. To access a channel's file descriptor, use channel-os-index; see Channels for more details.

 -- procedure: remap-file-descriptors! fd-spec ... returns unspecified
     Reassigns file descriptors to ports.  Each FD-SPEC specifies what port is to be mapped to what file descriptor: the first port gets file descriptor 0; the second, 1; and so on.  An FD-SPEC is either a port that reads from or writes to a file descriptor or #f; in the latter case, the corresponding file descriptor is not used.  Any open ports not listed are marked close-on-exec.  The same port may be moved to multiple new file descriptors.

     For example,

          (remap-file-descriptors! (current-output-port)
                                   #f
                                   (current-input-port)) lisp

          moves the current output port to file descriptor 0 (ie
          stdin) and the current input port to file descriptor 2
          (ie stderr).  File descriptor 1 (stdout) is not
          mapped to anything, and all other open ports (including anything that
          had the file descriptor 1) are marked close-on-exec.

 -- procedure: dup fd-port returns fd-port
 -- procedure: dup-switching-mode fd-port returns fd-port
 -- procedure: dup2 fd-port fdes returns fd-port
     These change FD-PORT's file descriptor and return new ports that have the ports' old file descriptors.  Dup uses the lowest unused file descriptor; dup2 uses the one provided. Dup-switching-mode is the same as dup except that the returned port is an input port if the argument was an output port and vice versa.  If any existing port uses the file descriptor passed to dup2, that port is closed.

 -- procedure: close-all-port port-or-channel ... unspecified
     Closes all ports or channels not listed as arguments.

 -- procedure: close-on-exec? channel returns boolean
 -- procedure: set-close-on-exec?! channel boolean returns unspecified
     These access the boolean flag that specifies whether CHANNEL will be closed when a new program is exec'd.

 -- procedure: i/o-flags fd-port returns file-options
 -- procedure: set-i/o-flags! fd-port file-options returns unspecified
     These access various POSIX file system access, file options for FD-PORT.  The options that may be read are append, nonblocking, read-only, read-write, and write-only; only the append and nonblocking options can be written.

 -- procedure: port-is-a-terminal? port returns boolean
 -- procedure: port-terminal-name port returns string or #f
     Port-is-a-terminal? returns true of PORT is a port that has an underlying file descriptor associated with a terminal.  For such ports, port-terminal-name returns the name of the terminal; for all others, it returns #f.

     Note: These procedures accept only ports, not channels.