Next: , Up: I/O system


4.5.1 Ports

While channels provide the low-level interface directly to the OS's I/O facilities, ports provide a more abstract & generalized mechanism for I/O transmission. Rather than being specific to channels or being themselves primitive I/O devices, ports are functionally parameterized. This section describes the usual I/O operations on ports. The next section describes the programmatic port parameterization mechanism, and the section following that describes the most commonly used built-in port abstraction, ports atop channels.

4.5.1.1 Port operations

The following names are exported by the i/o structure.

— procedure: input-port? value –> boolean
— procedure: output-port? value –> boolean

These return #t if their argument is both a port and either an input port or output port, respectively, or #f if neither condition is true.

— procedure: close-input-port port –> unspecified
— procedure: close-output-port port –> unspecified

Closes port, which must be an input port or an output port, respectively.

— procedure: char-ready? [port] –> boolean
— procedure: output-port-ready? port –> boolean

Char-ready? returns a true value if there is a character ready to be read from port and #f if there is no character ready. Port defaults to the current input port if absent; see below on current ports. Output-port-ready? returns a true value if port is ready to receive a single written character and #f if not.

— procedure: read-block block start count port [wait?] –> count-read or EOF
— procedure: write-block block start count port –> count-written
— procedure: write-string string port –> char-count-written

Read-block attempts to read count elements from port into block, which may be a string or a byte vector, starting at start. If fewer than count characters or bytes are available to read from port, and wait? is a true value or absent, read-block will wait until count characters are available and read into block; if wait? is #f, read-block immediately returns. Read-block returns the number of elements read into block, or an end of file object if the stream's end is immediately encountered. Write-block writes count elements from block, which may be a string or a byte vector, starting at start to port. Write-string is a convenience atop write-block for writing the entirety of a string to a port.

— procedure: newline [port] –> unspecified

Writes a newline character or character sequence to the output port port. Port defaults to the current output port; see below on current ports.

— procedure: disclose-port port –> disclosed

Returns a disclosed representation of port; see Writer.

— procedure: force-output port –> unspecified

Forces all buffered output in the output port port to be sent.

— procedure: make-null-output-port –> output-port

Returns an output port that will ignore any output it receives.

4.5.1.2 Current ports

Scheme48 keeps in its dynamic environment a set of `current' ports. These include R5RS's current input and output ports, as well as ports for general noise produced by the system, and ports for where error messages are printed. These procedures are exported by the i/o structure.

— procedure: current-input-port –> input-port
— procedure: current-output-port –> output-port
— procedure: current-noise-port –> output-port
— procedure: current-error-port –> output-port

These return the values in the current dynamic environment of the respective ports. Current-input-port and current-output-port are also exported by the scheme structure.

— procedure: input-port-option arguments –> input-port
— procedure: output-port-option arguments –> output-port

These are utilities for retrieving optional input and output port arguments from rest argument lists, defaulting to the current input or output ports. For example, assuming the newline character sequence is simply #\newline, newline might be written as:

          (define (newline . maybe-port)
            (write-char #\newline (output-port-option maybe-port)))

— procedure: silently thunk –> values

This stifles output from the current noise port in the dynamic extent of thunk, which is applied to zero arguments. Silently returns the values that thunk returns.

— procedure: with-current-ports input output error thunk –> values

With-current-ports dynamically binds the current input, output, and error ports to input, output, and error, respectively, in the dynamic extent of thunk, which is applied to zero arguments. The current noise port is also bound to error. With-current-ports returns the values that thunk returns.

Similarly to with-current-ports, the i/o-internal structure also exports these procedures:

— procedure: call-with-current-input-port port thunk –> values
— procedure: call-with-current-output-port port thunk –> values
— procedure: call-with-current-noise-port port thunk –> values

These bind individual current ports for the dynamic extent of each thunk, which is applied to zero arguments. These all return the values that thunk returns.