Ports (MIT/GNU Scheme 10.1.6)

Next: File Ports, Previous: Input/Output, 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]