(guile.info.gz) Ports and File Descriptors
Info Catalog
(guile.info.gz) Conventions
(guile.info.gz) POSIX
(guile.info.gz) File System
38.2 Ports and File Descriptors
===============================
Conventions generally follow those of scsh, The Scheme shell
(scsh).
File ports are implemented using low-level operating system I/O
Ports::
Note that some procedures (e.g., `recv!') will accept ports as
arguments, but will actually operate directly on the file descriptor
underlying the port. Any port buffering is ignored, including the
buffer which implements `peek-char' and `unread-char'.
The `force-output' and `drain-input' procedures can be used to clear
the buffers.
Each open file port has an associated operating system file
descriptor. File descriptors are generally not useful in Scheme
programs; however they may be needed when interfacing with foreign code
and the Unix environment.
A file descriptor can be extracted from a port and a new port can be
created from a file descriptor. However a file descriptor is just an
integer and the garbage collector doesn't recognize it as a reference
to the port. If all other references to the port were dropped, then
it's likely that the garbage collector would free the port, with the
side-effect of closing the file descriptor prematurely.
To assist the programmer in avoiding this problem, each port has an
associated "revealed count" which can be used to keep track of how many
times the underlying file descriptor has been stored in other places.
If a port's revealed count is greater than zero, the file descriptor
will not be closed when the port is garbage collected. A programmer
can therefore ensure that the revealed count will be greater than zero
if the file descriptor is needed elsewhere.
For the simple case where a file descriptor is "imported" once to
become a port, it does not matter if the file descriptor is closed when
the port is garbage collected. There is no need to maintain a revealed
count. Likewise when "exporting" a file descriptor to the external
environment, setting the revealed count is not required provided the
port is kept open (i.e., is pointed to by a live Scheme binding) while
the file descriptor is in use.
To correspond with traditional Unix behaviour, the three file
descriptors (0, 1 and 2) are automatically imported when a program
starts up and assigned to the initial values of the current input,
output and error ports. The revealed count for each is initially set to
one, so that dropping references to one of these ports will not result
in its garbage collection: it could be retrieved with fdopen or
fdes->ports.
-- Scheme Procedure: port-revealed port
-- C Function: scm_port_revealed (port)
Return the revealed count for PORT.
-- Scheme Procedure: set-port-revealed! port rcount
-- C Function: scm_set_port_revealed_x (port, rcount)
Sets the revealed count for a port to a given value. The return
value is unspecified.
-- Scheme Procedure: fileno port
-- C Function: scm_fileno (port)
Return the integer file descriptor underlying PORT. Does not
change its revealed count.
-- Scheme Procedure: port->fdes port
Returns the integer file descriptor underlying PORT. As a side
effect the revealed count of PORT is incremented.
-- Scheme Procedure: fdopen fdes modes
-- C Function: scm_fdopen (fdes, modes)
Return a new port based on the file descriptor FDES. Modes are
given by the string MODES. The revealed count of the port is
initialized to zero. The modes string is the same as that
accepted by open-file File Ports.
-- Scheme Procedure: fdes->ports fd
-- C Function: scm_fdes_to_ports (fd)
Return a list of existing ports which have FDES as an underlying
file descriptor, without changing their revealed counts.
-- Scheme Procedure: fdes->inport fdes
Returns an existing input port which has FDES as its underlying
file descriptor, if one exists, and increments its revealed count.
Otherwise, returns a new input port with a revealed count of 1.
-- Scheme Procedure: fdes->outport fdes
Returns an existing output port which has FDES as its underlying
file descriptor, if one exists, and increments its revealed count.
Otherwise, returns a new output port with a revealed count of 1.
-- Scheme Procedure: primitive-move->fdes port fd
-- C Function: scm_primitive_move_to_fdes (port, fd)
Moves the underlying file descriptor for PORT to the integer value
FDES without changing the revealed count of PORT. Any other ports
already using this descriptor will be automatically shifted to new
descriptors and their revealed counts reset to zero. The return
value is `#f' if the file descriptor already had the required
value or `#t' if it was moved.
-- Scheme Procedure: move->fdes port fdes
Moves the underlying file descriptor for PORT to the integer value
FDES and sets its revealed count to one. Any other ports already
using this descriptor will be automatically shifted to new
descriptors and their revealed counts reset to zero. The return
value is unspecified.
-- Scheme Procedure: release-port-handle port
Decrements the revealed count for a port.
-- Scheme Procedure: fsync object
-- C Function: scm_fsync (object)
Copies any unwritten data for the specified output file descriptor
to disk. If PORT/FD is a port, its buffer is flushed before the
underlying file descriptor is fsync'd. The return value is
unspecified.
-- Scheme Procedure: open path flags [mode]
-- C Function: scm_open (path, flags, mode)
Open the file named by PATH for reading and/or writing. FLAGS is
an integer specifying how the file should be opened. MODE is an
integer specifying the permission bits of the file, if it needs to
be created, before the umask is applied. The default is 666 (Unix
itself has no default).
FLAGS can be constructed by combining variables using `logior'.
Basic flags are:
-- Variable: O_RDONLY
Open the file read-only.
-- Variable: O_WRONLY
Open the file write-only.
-- Variable: O_RDWR
Open the file read/write.
-- Variable: O_APPEND
Append to the file instead of truncating.
-- Variable: O_CREAT
Create the file if it does not already exist.
See the Unix documentation of the `open' system call for
additional flags.
-- Scheme Procedure: open-fdes path flags [mode]
-- C Function: scm_open_fdes (path, flags, mode)
Similar to `open' but return a file descriptor instead of a port.
-- Scheme Procedure: close fd_or_port
-- C Function: scm_close (fd_or_port)
Similar to close-port ( close-port Closing.), but also works
on file descriptors. A side effect of closing a file descriptor
is that any ports using that file descriptor are moved to a
different file descriptor and have their revealed counts set to
zero.
-- Scheme Procedure: close-fdes fd
-- C Function: scm_close_fdes (fd)
A simple wrapper for the `close' system call. Close file
descriptor FD, which must be an integer. Unlike close (
close Ports and File Descriptors.), the file descriptor will be
closed even if a port is using it. The return value is
unspecified.
-- Scheme Procedure: unread-char char [port]
-- C Function: scm_unread_char (char, port)
Place CHAR in PORT so that it will be read by the next read
operation. If called multiple times, the unread characters will
be read again in last-in first-out order. If PORT is not
supplied, the current input port is used.
-- Scheme Procedure: unread-string str port
Place the string STR in PORT so that its characters will be read
in subsequent read operations. If called multiple times, the
unread characters will be read again in last-in first-out order.
If PORT is not supplied, the current-input-port is used.
-- Scheme Procedure: pipe
-- C Function: scm_pipe ()
Return a newly created pipe: a pair of ports which are linked
together on the local machine. The _car_ is the input port and
the _cdr_ is the output port. Data written (and flushed) to the
output port can be read from the input port. Pipes are commonly
used for communication with a newly forked child process. The
need to flush the output port can be avoided by making it
unbuffered using `setvbuf'.
Writes occur atomically provided the size of the data in bytes is
not greater than the value of `PIPE_BUF'. Note that the output
port is likely to block if too much data (typically equal to
`PIPE_BUF') has been written but not yet read from the input port.
The next group of procedures perform a `dup2' system call, if NEWFD
(an integer) is supplied, otherwise a `dup'. The file descriptor to be
duplicated can be supplied as an integer or contained in a port. The
type of value returned varies depending on which procedure is used.
All procedures also have the side effect when performing `dup2' that
any ports using NEWFD are moved to a different file descriptor and have
their revealed counts set to zero.
-- Scheme Procedure: dup->fdes fd_or_port [fd]
-- C Function: scm_dup_to_fdes (fd_or_port, fd)
Return a new integer file descriptor referring to the open file
designated by FD_OR_PORT, which must be either an open file port
or a file descriptor.
-- Scheme Procedure: dup->inport port/fd [newfd]
Returns a new input port using the new file descriptor.
-- Scheme Procedure: dup->outport port/fd [newfd]
Returns a new output port using the new file descriptor.
-- Scheme Procedure: dup port/fd [newfd]
Returns a new port if PORT/FD is a port, with the same mode as the
supplied port, otherwise returns an integer file descriptor.
-- Scheme Procedure: dup->port port/fd mode [newfd]
Returns a new port using the new file descriptor. MODE supplies a
mode string for the port ( open-file File Ports.).
-- Scheme Procedure: duplicate-port port modes
Returns a new port which is opened on a duplicate of the file
descriptor underlying PORT, with mode string MODES as for
open-file File Ports. The two ports will share a file position
and file status flags.
Unexpected behaviour can result if both ports are subsequently used
and the original and/or duplicate ports are buffered. The mode
string can include `0' to obtain an unbuffered duplicate port.
This procedure is equivalent to `(dup->port PORT MODES)'.
-- Scheme Procedure: redirect-port old new
-- C Function: scm_redirect_port (old, new)
This procedure takes two ports and duplicates the underlying file
descriptor from OLD-PORT into NEW-PORT. The current file
descriptor in NEW-PORT will be closed. After the redirection the
two ports will share a file position and file status flags.
The return value is unspecified.
Unexpected behaviour can result if both ports are subsequently used
and the original and/or duplicate ports are buffered.
This procedure does not have any side effects on other ports or
revealed counts.
-- Scheme Procedure: dup2 oldfd newfd
-- C Function: scm_dup2 (oldfd, newfd)
A simple wrapper for the `dup2' system call. Copies the file
descriptor OLDFD to descriptor number NEWFD, replacing the
previous meaning of NEWFD. Both OLDFD and NEWFD must be integers.
Unlike for dup->fdes or primitive-move->fdes, no attempt is made
to move away ports which are using NEWFD. The return value is
unspecified.
-- Scheme Procedure: port-mode port
Return the port modes associated with the open port PORT. These
will not necessarily be identical to the modes used when the port
was opened, since modes such as "append" which are used only
during port creation are not retained.
-- Scheme Procedure: port-for-each proc
-- C Function: scm_port_for_each (proc)
Apply PROC to each port in the Guile port table in turn. The
return value is unspecified. More specifically, PROC is applied
exactly once to every port that exists in the system at the time
PORT-FOR-EACH is invoked. Changes to the port table while
PORT-FOR-EACH is running have no effect as far as PORT-FOR-EACH is
concerned.
-- Scheme Procedure: setvbuf port mode [size]
-- C Function: scm_setvbuf (port, mode, size)
Set the buffering mode for PORT. MODE can be:
`_IONBF'
non-buffered
`_IOLBF'
line buffered
`_IOFBF'
block buffered, using a newly allocated buffer of SIZE bytes.
If SIZE is omitted, a default size will be used.
-- Scheme Procedure: fcntl object cmd [value]
-- C Function: scm_fcntl (object, cmd, value)
Apply COMMAND to the specified file descriptor or the underlying
file descriptor of the specified port. VALUE is an optional
integer argument.
Values for COMMAND are:
`F_DUPFD'
Duplicate a file descriptor
`F_GETFD'
Get flags associated with the file descriptor.
`F_SETFD'
Set flags associated with the file descriptor to VALUE.
`F_GETFL'
Get flags associated with the open file.
`F_SETFL'
Set flags associated with the open file to VALUE
`F_GETOWN'
Get the process ID of a socket's owner, for `SIGIO' signals.
`F_SETOWN'
Set the process that owns a socket to VALUE, for `SIGIO'
signals.
`FD_CLOEXEC'
The value used to indicate the "close on exec" flag with
`F_GETFL' or `F_SETFL'.
-- Scheme Procedure: flock file operation
-- C Function: scm_flock (file, operation)
Apply or remove an advisory lock on an open file. OPERATION
specifies the action to be done:
`LOCK_SH'
Shared lock. More than one process may hold a shared lock
for a given file at a given time.
`LOCK_EX'
Exclusive lock. Only one process may hold an exclusive lock
for a given file at a given time.
`LOCK_UN'
Unlock the file.
`LOCK_NB'
Don't block when locking. May be specified by bitwise OR'ing
it to one of the other operations.
The return value is not specified. FILE may be an open file
descriptor or an open file descriptor port.
-- Scheme Procedure: select reads writes excepts [secs [usecs]]
-- C Function: scm_select (reads, writes, excepts, secs, usecs)
This procedure has a variety of uses: waiting for the ability to
provide input, accept output, or the existence of exceptional
conditions on a collection of ports or file descriptors, or
waiting for a timeout to occur. It also returns if interrupted by
a signal.
READS, WRITES and EXCEPTS can be lists or vectors, with each
member a port or a file descriptor. The value returned is a list
of three corresponding lists or vectors containing only the
members which meet the specified requirement. The ability of port
buffers to provide input or accept output is taken into account.
Ordering of the input lists or vectors is not preserved.
The optional arguments SECS and USECS specify the timeout. Either
SECS can be specified alone, as either an integer or a real
number, or both SECS and USECS can be specified as integers, in
which case USECS is an additional timeout expressed in
microseconds. If SECS is omitted or is `#f' then select will wait
for as long as it takes for one of the other conditions to be
satisfied.
The scsh version of `select' differs as follows: Only vectors are
accepted for the first three arguments. The USECS argument is not
supported. Multiple values are returned instead of a list.
Duplicates in the input vectors appear only once in output. An
additional `select!' interface is provided.
Info Catalog
(guile.info.gz) Conventions
(guile.info.gz) POSIX
(guile.info.gz) File System
automatically generated byinfo2html