s48-refman/posix/io.texi

@node POSIX I/O utilities
@section I/O utilities

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

@cindex POSIX pipe I/O
@cindex pipe I/O
@deffn 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.
@end deffn

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

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

@strong{Note:} Channels may @emph{not} be passed to these procedures.
To access a channel's file descriptor, use @code{channel-os-index};
@pxref{Channels} for more details.
@end deffn

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

For example,

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

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

@cindex fd-port dup'ing
@deffn procedure dup fd-port @returns{} fd-port
@deffnx procedure dup-switching-mode fd-port @returns{} fd-port
@deffnx procedure dup2 fd-port fdes @returns{} fd-port
These change @var{fd-port}'s file descriptor and return new ports that
have the ports' old file descriptors.  @code{Dup} uses the lowest
unused file descriptor; @code{dup2} uses the one provided.
@code{Dup-switching-mode} is the same as @code{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
@code{dup2}, that port is closed.
@end deffn

@deffn procedure close-all-port port-or-channel @dots{} @returns unspecified
Closes all ports or channels not listed as arguments.
@end deffn

@deffn procedure close-on-exec? channel @returns{} boolean
@deffnx procedure set-close-on-exec?! channel boolean @returns{} unspecified
These access the boolean flag that specifies whether @var{channel} will
be closed when a new program is @code{exec}'d.
@end deffn

@cindex @code{fcntl}
@cindex POSIX @code{fcntl}
@cindex fd-port I/O flags
@cindex I/O flags
@deffn procedure i/o-flags fd-port @returns{} file-options
@deffnx procedure set-i/o-flags! fd-port file-options @returns{} unspecified
These access various @embedref{POSIX file system access, file options}
for @var{fd-port}.  The options that may be read are @code{append},
@code{nonblocking}, @code{read-only}, @code{read-write}, and
@code{write-only}; only the @code{append} and @code{nonblocking}
options can be written.
@end deffn

@cindex terminal ports
@cindex POSIX terminal ports
@deffn procedure port-is-a-terminal? port @returns{} boolean
@deffnx procedure port-terminal-name port @returns{} string or @code{#f}
@code{Port-is-a-terminal?} returns true of @var{port} is a port that
has an underlying file descriptor associated with a terminal.  For such
ports, @code{port-terminal-name} returns the name of the terminal; for
all others, it returns @code{#f}.

@strong{Note:} These procedures accept only ports, not channels.
@end deffn