Next: File Ports, Previous: Input/Output, Up: Input/Output [Contents][Index]
Ports represent input and output devices. To Scheme, an input port is a Scheme object that can deliver data upon command, while an output port is a Scheme object that can accept data. Whether the input and output port types are disjoint is implementation-dependent. (In MIT/GNU Scheme, there are input ports, output ports, and input/output ports.)
Different port types operate on different data. Scheme implementations are required to support textual ports and binary ports, but may also provide other port types.
A textual port supports reading or writing of individual
characters from or to a backing store containing characters using
read-char and write-char below, and it supports
operations defined in terms of characters, such as read and
write.
A binary port supports reading or writing of individual bytes
from or to a backing store containing bytes using read-u8 and
write-u8 below, as well as operations defined in terms of
bytes. Whether the textual and binary port types are disjoint is
implementation-dependent. (In MIT/GNU Scheme, textual ports and
binary ports are distinct.)
Ports can be used to access files, devices, and similar things on the host system on which the Scheme program is running.
It is an error if procedure does not accept one argument.
The call-with-port procedure calls procedure with
port as an argument. If procedure returns, then the port
is closed automatically and the values yielded by procedure are
returned. If procedure does not return, then the port must not
be closed automatically unless it is possible to prove that the port
will never again be used for a read or write operation.
Rationale: Because Scheme’s escape procedures have unlimited
extent, it is possible to escape from the current continuation but
later to resume it. If implementations were permitted to close the
port on any escape from the current continuation, then it would be
impossible to write portable code using both
call-with-current-continuation and call-with-port.
The limit argument must be a nonnegative integer. It is an error if procedure does not accept one argument.
This procedure uses a continuation to escape from procedure if it tries to write more than limit characters.
It calls procedure with a special output port as an argument. Up to limit characters may be written to that output port, and those characters are transparently written through to output-port.
If the number of characters written to that port exceeds limit,
then the escape continuation is invoked and #t is returned.
Otherwise, procedure returns normally and #f is returned.
Note that if procedure writes exactly limit characters,
then the escape continuation is not invoked, and #f is
returned.
In no case does call-with-truncated-output-port close
output-port.
These procedures return #t if object is an input port,
output port, input/output port, textual port, binary port, or any kind
of port, respectively. Otherwise they return #f.
Returns #t if port is still open and capable of
performing input or output, respectively, and #f otherwise.
Returns the current default input port, output port, or error port (an
output port), respectively. These procedures are parameter objects,
which can be overridden with parameterize. The initial
bindings for these are implementation-defined textual ports.
Returns an output port suitable for generating “notifications”, that
is, messages to the user that supply interesting information about the
execution of a program. For example, the load procedure writes
messages to this port informing the user that a file is being loaded.
This procedure is a parameter object, which can be overridden with
parameterize.
Returns an output port suitable for generating “tracing” information
about a program’s execution. The output generated by the trace
procedure is sent to this port.
This procedure is a parameter object, which can be overridden with
parameterize.
Returns an I/O port suitable for querying or prompting the user. The standard prompting procedures use this port by default (see Prompting).
This procedure is a parameter object, which can be overridden with
parameterize.
Closes the resource associated with port, rendering the port incapable of delivering or accepting data. It is an error to apply the last two procedures to a port which is not an input or output port, respectively. Scheme implementations may provide ports which are simultaneously input and output ports, such as sockets; the close-input-port and close-output-port procedures can then be used to close the input and output sides of the port independently.
These routines have no effect if the port has already been closed.
These procedures are deprecated; instead call the corresponding parameters with an argument.
These procedures are deprecated; instead use
parameterize on the corresponding parameters.
console-i/o-port is an I/O port that communicates
with the “console”. Under unix, the console is the controlling
terminal of the Scheme process. Under Windows, the console is the
window that is created when Scheme starts up.
This variable is rarely used; instead programs should use one of the standard ports defined above. This variable should not be modified.
Next: File Ports, Previous: Input/Output, Up: Input/Output [Contents][Index]