Next: , Previous: POSIX time, Up: POSIX interface


8.8 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 –> [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 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 –> boolean
— procedure: port->fd port –> 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 ... –> 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))

moves the current output port to file descriptor 0 (i.e. stdin) and the current input port to file descriptor 2 (i.e. 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 –> fd-port
— procedure: dup-switching-mode fd-port –> fd-port
— procedure: dup2 fd-port fdes –> 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 –> boolean
— procedure: set-close-on-exec?! channel boolean –> 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 –> file-options
— procedure: set-i/o-flags! fd-port file-options –> unspecified

These access various 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 –> boolean
— procedure: port-terminal-name port –> 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.