Conventions generally follow those of scsh, The Scheme shell (scsh).
File ports are implemented using low-level operating system I/O facilities, with optional buffering to improve efficiency; see File 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
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, three file descriptors
(0, 1, and 2) are automatically imported when a program starts up and
assigned to the initial values of the current/standard input, output,
and error ports, respectively. 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
Return the revealed count for port.
Sets the revealed count for a port to rcount. The return value is unspecified.
Return the integer file descriptor underlying port. Does not change its revealed count.
Returns the integer file descriptor underlying port. As a side effect the revealed count of port is incremented.
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
open-file (see open-file).
Return a list of existing ports which have fdes as an underlying file descriptor, without changing their revealed counts.
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.
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.
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.
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.
Decrements the revealed count for a port.
Copies any unwritten data for the specified output file descriptor to disk. If port_or_fd is a port, its buffer is flushed before the underlying file descriptor is fsync’d. The return value is unspecified.
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 (see Processes) is applied. The default is 666 (Unix itself has no default).
flags can be constructed by combining variables using
Basic flags are:
Open the file read-only.
Open the file write-only.
Open the file read/write.
Append to the file instead of truncating.
Create the file if it does not already exist.
See File Status Flags in The GNU C Library Reference Manual, for additional flags.
open but return a file descriptor instead of
close-port (see close-port),
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.
A simple wrapper for the
close system call. Close file
descriptor fd, which must be an integer. Unlike
the file descriptor will be closed even if a port is using it. The
return value is unspecified.
Place char in port so that it will be read by the next read operation on that port. If called multiple times, the unread characters will be read again in “last-in, first-out” order (i.e. a stack). If port is not supplied, the current input port is used.
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.
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
A write of up to
PIPE_BUF many bytes to a pipe is atomic,
meaning when done it goes into the pipe instantaneously and as a
contiguous block (see Atomicity of Pipe I/O in The GNU C Library Reference Manual).
Note that the output port is likely to block if too much data has been
written but not yet read from the input port. Typically the capacity
The next group of procedures perform a
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.
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.
Returns a new input port using the new file descriptor.
Returns a new output port using the new file descriptor.
Returns a new port if port/fd is a port, with the same mode as the supplied port, otherwise returns an integer file descriptor.
Returns a new port using the new file descriptor. mode supplies a mode string for the port (see open-file).
Returns a new port which is opened on a duplicate of the file descriptor underlying port, with mode string modes as for open-file. 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
This procedure is equivalent to
(dup->port port modes).
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.
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
primitive-move->fdes, no attempt
is made to move away ports which are using newfd.
The return value is unspecified.
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.
Apply proc to each port in the Guile port table
(FIXME: what is 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
port-for-each is concerned.
The C function
scm_port_for_each takes a Scheme procedure
encoded as a
SCM value, while
a pointer to a C function and passes along a arbitrary data
Set the buffering mode for port. mode can be:
block buffered, using a newly allocated buffer of size bytes. If size is omitted, a default size will be used.
Only certain types of ports are supported, most importantly file ports.
Apply cmd on port/fd, either a port or file descriptor.
The value argument is used by the
SET commands described
below, it’s an integer value.
Values for cmd are:
Duplicate the file descriptor, the same as
Get or set flags associated with the file descriptor. The only flag is the following,
“Close on exec”, meaning the file descriptor will be closed on an
exec call (a successful such call). For example to set that
(fcntl port F_SETFD FD_CLOEXEC)
Or better, set it but leave any other possible future flags unchanged,
(fcntl port F_SETFD (logior FD_CLOEXEC (fcntl port F_GETFD)))
Get or set flags associated with the open file. These flags are
O_RDONLY etc described under
A common use is to set
O_NONBLOCK on a network socket. The
following sets that flag, and leaves other flags unchanged.
(fcntl sock F_SETFL (logior O_NONBLOCK (fcntl sock F_GETFL)))
Get or set the process ID of a socket’s owner, for
Apply or remove an advisory lock on an open file. operation specifies the action to be done:
Shared lock. More than one process may hold a shared lock for a given file at a given time.
Exclusive lock. Only one process may hold an exclusive lock for a given file at a given time.
Unlock the file.
Don’t block when locking. This is combined with one of the other
logior (see Bitwise Operations). If
flock would block an
EWOULDBLOCK error is thrown
The return value is not specified. file may be an open file descriptor or an open file descriptor port.
flock does not lock files across NFS.
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.
When an error occurs, of if it is interrupted by a signal, this
procedure throws a
system-error). In case of an
interruption, the associated error number is EINTR.
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
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.
select! interface is provided.