12.1 Ports

Ports produce and consume bytes. When a port is provided to a character-based operation, the port’s bytes are decoded; see Encodings and Locales.

When a port corresponds to a file, network connection, or some other system resource, it must be explicitly closed via close-input-port or close-output-port (or indirectly via custodian-shutdown-all) to release low-level resources associated with the port. For any kind of port, after it is closed, attempting to read from or write to the port raises exn:fail.

The global variable eof is bound to the end-of-file value, and eof-object? returns #t only when applied to this value. Reading from a port produces an end-of-file result when the port has no more data, but some ports may also return end-of-file mid-stream. For example, a port connected to a Unix terminal returns an end-of-file when the user types control-D; if the user provides more input, the port returns additional bytes after the end-of-file.

Every port has a name, as reported by object-name. The name can be any value, and it is used mostly for error-reporting purposes. The read-syntax procedure uses the name of an input port as the default source location for the syntax objects that it produces.

A port can be used as a synchronizable event. An input port is ready for synchronization when read-byte would not block, and an output port is ready for synchronization when write-bytes-avail would not block or when the port contains buffered characters and write-bytes-avail* can flush part of the buffer (although write-bytes-avail might block). A value that can act as both an input port and an output port acts as an input port for a synchronizable event. The synchronization result of a port is the port itself.

    12.1.1 Encodings and Locales

    12.1.2 Managing Ports

    12.1.3 Port Buffers and Positions

    12.1.4 Counting Positions, Lines, and Columns

    12.1.5 File Ports

    12.1.6 String Ports

    12.1.7 Pipes

    12.1.8 Structures as Ports

    12.1.9 Custom Ports

    12.1.10 More Port Constructors, Procedures, and Events Port String and List Conversions Creating Ports Port Events Copying Streams