13.1 Ports🔗ℹ

A port is an input or output stream for a file, network connection, terminal, etc. An input port is specifically for input, while an output port is specifically for output; it is possible for an object to be both an input and output port.

The Port.EOF annotation is satisfied by the Port.eof value.

A port’s default buffer mode depends on the communication channel that it represents. A file port is nomrally #'block buffered. The initial stdin port is #'block buffered. The initial stdout port is #'line buffered if it writers to a terminal, #'block buffered otherwise. The initial stderr port’s buffer mode is #'none.

Calling Port.position without pos on a port other than a Port.FileStream, Port.Input.String, or Port.Output.String port returns the number of bytes that have been read from that port if the position is known.

For Port.FileStream, Port.Input.String, or Port.Output.String ports, providing pos sets the read/write position relative to the beginning of the file or (byte) string if pos is a number, or to the current end of the file or (byte) string if pos is Port.eof. For other kinds of ports, an exception is thrown when pos is supplied. Furthermore, not all Port.FileStream ports support setting the position; if pos is supplied for such a port, the Exn.Fail.Filesystem exception is thrown.

When file-position sets the position beyond the current size of an output file or (byte) string, the file/string is enlarged to size pos, and the new region is filled with 0 bytes in the case of a file. In the case of a file output port, the file might not be enlarged until more data is written to the file; in that case, beware that writing to a file opened in #'append mode on Unix and Mac OS will reset the file pointer to the end of a file before each write, which defeats file enlargement via Port.position. If pos is beyond the end of an input file or (byte) string, then reading thereafter returns eof without changing the port’s position.

When changing the file position for an output port, the port is first flushed if its buffer is not empty. Similarly, setting the position for an input port clears the port’s buffer (even if the new position is the same as the old position). However, although input and output ports produced by open-input-output-file share the file position, setting the position via one port does not flush the other port’s buffer.

The Port.next_location method with zero arguments reports a line, column, and offset for the next character to be read from the port. If tracking is not enabled, then the first two results will be #false, but port.position()+1 may be returned as an approximation for the last result (i.e., a position measured in bytes used as an approximation of the number of characters read). Calling Port.next_location with arguments attempts to set the next location, but the attempt is ignored if location tracking has not been enabled or if the port does not support external adjustments.

This procedure is intended for use with special devices that can be opened by only one process, such as "COM1" in Windows. For regular files, sharing the file descriptor can be confusing. For example, using one port does not automatically flush the other port’s buffer, and reading or writing in one port moves the file position (if any) for the other port. For regular files, use separate Port.Input.open_file and Port.Output.open_file calls to avoid confusion.