12.1 Ports

Ports produce and/or consume bytes. An input port produces bytes, while an output port produces bytes (and some ports are both input ports and output ports). When an input port is provided to a character-based operation, the bytes are decoded to a character, and character-based output operations similarly encode the character to bytes; see Encodings and Locales. In addition to bytes and characters encoded as bytes, some ports can produce and/or consume arbitrary values as special results.

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.

Data produced by a input port can be read or peeked. When data is read, it is considered consumed and removed from the port’s stream. When data is peeked, it remains in the port’s stream to be returned again by the next read or peek. Previously peeked data can be committed, which causes the data to be removed from the port as for a read in a way that can be synchronized with other attempts to peek or read through a synchronizable event. Both read and peek operations are normally blocking, in the sense that the read or peek operation does not complete until data is available from the port; non-blocking variants of read and peek operations are also available.

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.