5.8.2.6 Input and output ports

The operations described in this section are common to input and output ports, both binary and textual. A port may also have an associated position that specifies a particular place within its data sink or source, and may also provide operations for inspecting and setting that place.

Procedure: port? obj

Return #t if the argument is a port, #f otherwise.

Procedure: port-transcoder port

Return the transcoder associated with port if port is textual and has an associated transcoder, and returns #f if port is binary or does not have an associated transcoder.

Procedure: textual-port? port

Procedure: binary-port? port

The textual-port? procedure returns #t if port is textual, and returns #f otherwise.

The binary-port? procedure returns #t if port is binary, and returns #f otherwise.

Procedure: transcoded-port binary-port transcoder

The transcoded-port procedure returns a new textual port with the specified transcoder. Otherwise the new textual port’s state is largely the same as that of binary-port.

If binary-port is an input port, the new textual port will be an input port and will transcode the bytes that have not yet been read from binary-port. If binary-port is an output port, the new textual port will be an output port and will transcode output characters into bytes that are written to the byte sink represented by binary-port.

As a side effect, however, transcoded-port closes binary-port in a special way that allows the new textual port to continue to use the byte source or sink represented by binary-port, even though binary-port itself is closed and cannot be used by the input and output operations described in this chapter.

Procedure: port-has-port-position? port

Procedure: port-position port

The port-has-port-position? procedure returns #t if the port supports the port-position operation, and #f otherwise.

For a binary port, port-position returns the index of the position at which the next byte would be read from or written to the port as an exact non–negative integer object. For a textual port, port-position returns a value of some implementation–dependent type representing the port’s position; this value may be useful only as the pos argument to set-port-position!, if the latter is supported on the port (see below).

If the port does not support the operation, port-position raises an exception with condition type &assertion.

NOTE For a textual port, the port position may or may not be an integer object. If it is an integer object, the integer object does not necessarily correspond to a byte or character position.

Procedure: port-has-set-port-position!? port

Procedure: set-port-position! port pos

If port is a binary port, pos should be a non–negative exact integer object. If port is a textual port, pos should be the return value of a call to port-position on port.

The port-has-set-port-position!? procedure returns #t if the port supports the set-port-position! operation, and #f otherwise.

The set-port-position! procedure raises an exception with condition type &assertion if the port does not support the operation, and an exception with condition type &i/o-invalid-position if pos is not in the range of valid positions of port. Otherwise, it sets the current position of the port to pos. If port is an output port, set-port-position! first flushes port.

If port is a binary output port and the current position is set beyond the current end of the data in the underlying data sink, the object is not extended until new data is written at that position. The contents of any intervening positions are unspecified. Binary ports created by open-file-output-port and open-file-input/output-port can always be extended in this manner within the limits of the underlying operating system. In other cases, attempts to set the port beyond the current end of data in the underlying object may result in an exception with condition type &i/o-invalid-position.

Procedure: close-port port

Closes the port, rendering the port incapable of delivering or accepting data. If port is an output port, it is flushed before being closed. This has no effect if the port has already been closed. A closed port is still a port. The close-port procedure returns unspecified values.

Procedure: call-with-port port proc

proc must accept one argument. The call-with-port procedure calls proc with port as an argument. If proc returns, port is closed automatically and the values returned by proc are returned. If proc does not return, port is not closed automatically, except perhaps when it is possible to prove that port will never again be used for an input or output operation.