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.