Next: , Previous: , Up: Input/Output   [Contents][Index]


14.1 Ports

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.

standard procedure: call-with-port port procedure

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.

procedure: call-with-truncated-output-port limit output-port procedure

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.

standard procedure: input-port? object
standard procedure: output-port? object
procedure: i/o-port? object
standard procedure: textual-port? object
standard procedure: binary-port? object
standard procedure: port? object

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.

standard procedure: input-port-open? port
standard procedure: output-port-open? port

Returns #t if port is still open and capable of performing input or output, respectively, and #f otherwise.

standard parameter: current-input-port [input-port]
standard parameter: current-output-port [output-port]
standard parameter: current-error-port [output-port]

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.

parameter: notification-output-port [output-port]

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.

parameter: trace-output-port [output-port]

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.

parameter: interaction-i/o-port [i/o-port]

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.

standard procedure: close-port port
standard procedure: close-input-port port
standard procedure: close-output-port port

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.

obsolete procedure: set-current-input-port! input-port
obsolete procedure: set-current-output-port! output-port
obsolete procedure: set-notification-output-port! output-port
obsolete procedure: set-trace-output-port! output-port
obsolete procedure: set-interaction-i/o-port! i/o-port

These procedures are deprecated; instead call the corresponding parameters with an argument.

obsolete procedure: with-input-from-port input-port thunk
obsolete procedure: with-output-to-port output-port thunk
obsolete procedure: with-notification-output-port output-port thunk
obsolete procedure: with-trace-output-port output-port thunk
obsolete procedure: with-interaction-i/o-port i/o-port thunk

These procedures are deprecated; instead use parameterize on the corresponding parameters.

variable: console-i/o-port

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]