r6rs-lib

#
Chapter 8
I/O

This chapter describes Scheme’s libraries for performing input and output:

- The `(rnrs io ports (6))` library (section 8.2) is an I/O layer for conventional, imperative buffered input and output with text and binary data.

- The `(rnrs io simple (6))` library (section 8.3) is a convenience library atop the `(rnrs io ports (6))` library for textual I/O, compatible with the traditional Scheme I/O procedures [8].

Section 8.1 defines a condition-type hierarchy that is exported by both the `(rnrs io ports (6))` and `(rnrs io simple (6))` libraries.

## 8.1 Condition types

The procedures described in this chapter, when they detect an exceptional situation that arises from an “I/O errors”, raise an exception with condition type `&i/o`.

The condition types and corresponding predicates and accessors are exported by both the `(rnrs io ports (6))` and `(rnrs io simple (6))` libraries. They are also exported by the `(rnrs files (6))` library described in chapter 9.

``&i/o`` condition type
`(make-i/o-error)` procedure
`(i/o-error? obj)` procedure

This condition type could be defined by

`(define-condition-type &i/o &error
make-i/o-error i/o-error?)

`

This is a supertype for a set of more specific I/O errors.

``&i/o-read`` condition type
`(make-i/o-read-error)` procedure
`(i/o-read-error? obj)` procedure

This condition type could be defined by

`(define-condition-type &i/o-read &i/o
make-i/o-read-error i/o-read-error?)

`

This condition type describes read errors that occurred during an I/O operation.

``&i/o-write`` condition type
`(make-i/o-write-error)` procedure
`(i/o-write-error? obj)` procedure

This condition type could be defined by

`(define-condition-type &i/o-write &i/o
make-i/o-write-error i/o-write-error?)

` This condition type describes write errors that occurred during an I/O operation.

``&i/o-invalid-position`` condition type
`(make-i/o-invalid-position-error position)` procedure
`(i/o-invalid-position-error? obj)` procedure
`(i/o-error-position condition)` procedure

This condition type could be defined by

`(define-condition-type &i/o-invalid-position &i/o
make-i/o-invalid-position-error
i/o-invalid-position-error?
(position i/o-error-position))

`

This condition type describes attempts to set the file position to an invalid position. Position should be the file position that the program intended to set. This condition describes a range error, but not an assertion violation.

``&i/o-filename`` condition type
`(make-i/o-filename-error filename)` procedure
`(i/o-filename-error? obj)` procedure
`(i/o-error-filename condition)` procedure

This condition type could be defined by

`(define-condition-type &i/o-filename &i/o
make-i/o-filename-error i/o-filename-error?
(filename i/o-error-filename))

`

This condition type describes an I/O error that occurred during an operation on a named file. Filename should be the name of the file.

``&i/o-file-protection`` condition type
`(make-i/o-file-protection-error filename)` procedure
`(i/o-file-protection-error? obj)` procedure

This condition type could be defined by

`(define-condition-type &i/o-file-protection
&i/o-filename
make-i/o-file-protection-error
i/o-file-protection-error?)

`

A condition of this type specifies that an operation tried to operate on a named file with insufficient access rights.

``&i/o-file-is-read-only`` condition type
`(make-i/o-file-is-read-only-error filename)` procedure
`(i/o-file-is-read-only-error? obj)` procedure

This condition type could be defined by

`(define-condition-type &i/o-file-is-read-only
&i/o-file-protection
make-i/o-file-is-read-only-error
i/o-file-is-read-only-error?)

`

A condition of this type specifies that an operation tried to operate on a named read-only file under the assumption that it is writeable.

``&i/o-file-already-exists`` condition type
`(make-i/o-file-already-exists-error filename)` procedure
`(i/o-file-already-exists-error? obj)` procedure

This condition type could be defined by

`(define-condition-type &i/o-file-already-exists
&i/o-filename
make-i/o-file-already-exists-error
i/o-file-already-exists-error?)

` A condition of this type specifies that an operation tried to operate on an existing named file under the assumption that it did not exist.

``&i/o-file-does-not-exist`` condition type
`(make-i/o-file-does-not-exist-error filename)` procedure
`(i/o-file-does-not-exist-error? obj)` procedure

This condition type could be defined by

`(define-condition-type &i/o-file-does-not-exist
&i/o-filename
make-i/o-file-does-not-exist-error
i/o-file-does-not-exist-error?)

`

A condition of this type specifies that an operation tried to operate on an non-existent named file under the assumption that it existed.

``&i/o-port`` condition type
`(make-i/o-port-error port)` procedure
`(i/o-port-error? obj)` procedure
`(i/o-error-port condition)` procedure

This condition type could be defined by

`(define-condition-type &i/o-port &i/o
make-i/o-port-error i/o-port-error?
(port i/o-error-port))

`

This condition type specifies the port with which an I/O error is associated. Port should be the port. Conditions raised by procedures accepting a port as an argument should include an `&i/o-port-error` condition.

## 8.2 Port I/O

The `(rnrs io ports (6))`library defines an I/O layer for conventional, imperative buffered input and output. A port represents a buffered access object for a data sink or source or both simultaneously. The library allows ports to be created from arbitrary data sources and sinks.

The `(rnrs io ports (6))` library distinguishes between input ports and output ports. An input port is a source for data, whereas an output port is a sink for data. A port may be both an input port and an output port; such a port typically provides simultaneous read and write access to a file or other data.

The `(rnrs io ports (6))` library also distinguishes between binary ports, which are sources or sinks for uninterpreted bytes, and textual ports, which are sources or sinks for characters and strings.

This section uses input-port, output-port, binary-port, textual-port, binary-input-port, textual-input-port, binary-output-port, textual-output-port, and port as parameter names for arguments that must be input ports (or combined input/output ports), output ports (or combined input/output ports), binary ports, textual ports, binary input ports, textual input ports, binary output ports, textual output ports, or any kind of port, respectively.

### 8.2.1 File names

Some of the procedures described in this chapter accept a file name as an argument. Valid values for such a file name include strings that name a file using the native notation of filesystem paths on an implementation’s underlying operating system, and may include implementation-dependent values as well.

A filename parameter name means that the corresponding argument must be a file name.

### 8.2.2 File options

When opening a file, the various procedures in this library accept a `file-options` object that encapsulates flags to specify how the file is to be opened. A `file-options` object is an enum-set (see chapter 14) over the symbols constituting valid file options. A file-options parameter name means that the corresponding argument must be a file-options object.

`(file-options <file-options symbol> `...`)` syntax

Each <file-options symbol> must be a symbol. The `file-options` syntax returns a file-options object that encapsulates the specified options.

When supplied to an operation that opens a file for output, the file-options object returned by `(file-options)` specifies that the file is created if it does not exist and an exception with condition type `&i/o-file-already-exists` is raised if it does exist. The following standard options can be included to modify the default behavior.

- `no-create` If the file does not already exist, it is not created; instead, an exception with condition type `&i/o-file-does-not-exist` is raised. If the file already exists, the exception with condition type `&i/o-file-already-exists` is not raised and the file is truncated to zero length.

- `no-fail` If the file already exists, the exception with condition type `&i/o-file-already-exists` is not raised, even if `no-create` is not included, and the file is truncated to zero length.

- `no-truncate` If the file already exists and the exception with condition type `&i/o-file-already-exists` has been inhibited by inclusion of `no-create` or `no-fail`, the file is not truncated, but the port’s current position is still set to the beginning of the file.

These options have no effect when a file is opened only for input. Symbols other than those listed above may be used as <file-options symbol>s; they have implementation-specific meaning, if any.

> Note: Only the name of <file-options symbol> is significant.

### 8.2.3 Buffer modes

Each port has an associated buffer mode. For an output port, the buffer mode defines when an output operation flushes the buffer associated with the output port. For an input port, the buffer mode defines how much data will be read to satisfy read operations. The possible buffer modes are the symbols `none` for no buffering, `line` for flushing upon line endings and reading up to line endings, or other implementation-dependent behavior, and `block` for arbitrary buffering. This section uses the parameter name buffer-mode for arguments that must be buffer-mode symbols.

If two ports are connected to the same mutable source, both ports are unbuffered, and reading a byte or character from that shared source via one of the two ports would change the bytes or characters seen via the other port, a lookahead operation on one port will render the peeked byte or character inaccessible via the other port, while a subsequent read operation on the peeked port will see the peeked byte or character even though the port is otherwise unbuffered.

In other words, the semantics of buffering is defined in terms of side effects on shared mutable sources, and a lookahead operation has the same side effect on the shared source as a read operation.

`(buffer-mode <buffer-mode symbol>)` syntax

<Buffer-mode symbol> must be a symbol whose name is one of `none`, `line`, and `block`. The result is the corresponding symbol, and specifies the associated buffer mode.

> Note: Only the name of <buffer-mode symbol> is significant.

`(buffer-mode? obj)` procedure

Returns `#t` if the argument is a valid buffer-mode symbol, and returns `#f` otherwise.

### 8.2.4 Transcoders

Several different Unicode encoding schemes describe standard ways to encode characters and strings as byte sequences and to decode those sequences [12]. Within this document, a codec is an immutable Scheme object that represents a Unicode or similar encoding scheme.

An end-of-line style is a symbol that, if it is not `none`, describes how a textual port transcodes representations of line endings.

A transcoder is an immutable Scheme object that combines a codec with an end-of-line style and a method for handling decoding errors. Each transcoder represents some specific bidirectional (but not necessarily lossless), possibly stateful translation between byte sequences and Unicode characters and strings. Every transcoder can operate in the input direction (bytes to characters) or in the output direction (characters to bytes). A transcoder parameter name means that the corresponding argument must be a transcoder.

A binary port is a port that supports binary I/O, does not have an associated transcoder and does not support textual I/O. A textual port is a port that supports textual I/O, and does not support binary I/O. A textual port may or may not have an associated transcoder.

`(latin-1-codec)` procedure
`(utf-8-codec)` procedure
`(utf-16-codec)` procedure

These are predefined codecs for the ISO 8859-1, UTF-8, and UTF-16 encoding schemes [12].

A call to any of these procedures returns a value that is equal in the sense of `eqv?` to the result of any other call to the same procedure.

`(eol-style <eol-style symbol>)` syntax

<Eol-style symbol> should be a symbol whose name is one of `lf`, `cr`, `crlf`, `nel`, `crnel`, `ls`, and `none`. The form evaluates to the corresponding symbol. If the name of eol-style symbol is not one of these symbols, the effect and result are implementation-dependent; in particular, the result may be an eol-style symbol acceptable as an eol-style argument to `make-transcoder`. Otherwise, an exception is raised.

All eol-style symbols except `none` describe a specific line-ending encoding:

`lf` | <linefeed>
`cr` | <carriage return>
`crlf` | <carriage return> <linefeed>
`nel` | <next line>
`crnel` | <carriage return> <next line>
`ls` | <line separator>

For a textual port with a transcoder, and whose transcoder has an eol-style symbol `none`, no conversion occurs. For a textual input port, any eol-style symbol other than `none` means that all of the above line-ending encodings are recognized and are translated into a single linefeed. For a textual output port, `none` and `lf` are equivalent. Linefeed characters are encoded according to the specified eol-style symbol, and all other characters that participate in possible line endings are encoded as is.

> Note: Only the name of <eol-style symbol> is significant.

`(native-eol-style)` procedure

Returns the default end-of-line style of the underlying platform, e.g., `lf` on Unix and `crlf` on Windows.

``&i/o-decoding`` condition type
`(make-i/o-decoding-error port)` procedure
`(i/o-decoding-error? obj)` procedure

This condition type could be defined by

`(define-condition-type &i/o-decoding &i/o-port
make-i/o-decoding-error i/o-decoding-error?)

`

An exception with this type is raised when one of the operations for textual input from a port encounters a sequence of bytes that cannot be translated into a character or string by the input direction of the port’s transcoder.

When such an exception is raised, the port’s position is past the invalid encoding.

``&i/o-encoding`` condition type
`(make-i/o-encoding-error port char)` procedure
`(i/o-encoding-error? obj)` procedure
`(i/o-encoding-error-char condition)` procedure

This condition type could be defined by

`(define-condition-type &i/o-encoding &i/o-port
make-i/o-encoding-error i/o-encoding-error?
(char i/o-encoding-error-char))

`

An exception with this type is raised when one of the operations for textual output to a port encounters a character that cannot be translated into bytes by the output direction of the port’s transcoder. Char is the character that could not be encoded.

`(error-handling-mode <error-handling-mode symbol>)` syntax

<Error-handling-mode symbol> should be a symbol whose name is one of `ignore`, `raise`, and `replace`. The form evaluates to the corresponding symbol. If error-handling-mode symbol is not one of these identifiers, effect and result are implementation-dependent: The result may be an error-handling-mode symbol acceptable as a handling-mode argument to `make-transcoder`. If it is not acceptable as a handling-mode argument to `make-transcoder`, an exception is raised.

> Note: Only the name of <error-handling-style symbol> is significant.

The error-handling mode of a transcoder specifies the behavior of textual I/O operations in the presence of encoding or decoding errors.

If a textual input operation encounters an invalid or incomplete character encoding, and the error-handling mode is `ignore`, an appropriate number of bytes of the invalid encoding are ignored and decoding continues with the following bytes. If the error-handling mode is `replace`, the replacement character U+FFFD is injected into the data stream, an appropriate number of bytes are ignored, and decoding continues with the following bytes. If the error-handling mode is `raise`, an exception with condition type `&i/o-decoding` is raised.

If a textual output operation encounters a character it cannot encode, and the error-handling mode is `ignore`, the character is ignored and encoding continues with the next character. If the error-handling mode is `replace`, a codec-specific replacement character is emitted by the transcoder, and encoding continues with the next character. The replacement character is U+FFFD for transcoders whose codec is one of the Unicode encodings, but is the `?` character for the Latin-1 encoding. If the error-handling mode is `raise`, an exception with condition type `&i/o-encoding` is raised.

`(make-transcoder codec)` procedure
`(make-transcoder codec eol-style)` procedure
`(make-transcoder codec eol-style handling-mode)` procedure

Codec must be a codec; eol-style, if present, an eol-style symbol; and handling-mode, if present, an error-handling-mode symbol. Eol-style may be omitted, in which case it defaults to the native end-of-line style of the underlying platform. Handling-mode may be omitted, in which case it defaults to `replace`. The result is a transcoder with the behavior specified by its arguments.

`(native-transcoder)` procedure

Returns an implementation-dependent transcoder that represents a possibly locale-dependent “native” transcoding.

`(transcoder-codec transcoder)` procedure
`(transcoder-eol-style transcoder)` procedure
`(transcoder-error-handling-mode transcoder)` procedure

These are accessors for transcoder objects; when applied to a transcoder returned by `make-transcoder`, they return the codec, eol-style, and handling-mode arguments, respectively.

`(bytevector->string bytevector transcoder)` procedure

Returns the string that results from transcoding the bytevector according to the input direction of the transcoder.

`(string->bytevector string transcoder)` procedure

Returns the bytevector that results from transcoding the string according to the output direction of the transcoder.

### 8.2.5 End-of-file object

The end-of-file object is returned by various I/O procedures when they reach end of file.

`(eof-object)` procedure

Returns the end-of-file object.

`(eqv? (eof-object) (eof-object))
⇒ `#t`
(eq? (eof-object) (eof-object))
⇒ `#t`

`

> Note: The end-of-file object is not a datum value, and thus has no external representation.

`(eof-object? obj)` procedure

Returns `#t` if obj is the end-of-file object, `#f` otherwise.

### 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.

`(port? obj)` procedure

Returns `#t` if the argument is a port, and returns `#f` otherwise.

`(port-transcoder port)` procedure

Returns 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.

`(textual-port? port)` procedure
`(binary-port? port)` procedure

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.

`(transcoded-port binary-port transcoder)` procedure

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.

`(port-has-port-position? port)` procedure
`(port-position port)` procedure

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

For a binary port, the `port-position` procedure 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.

`(port-has-set-port-position!? port)` procedure
`(set-port-position! port pos)` procedure

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. (See `flush-output-port`, section 8.2.10.)

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`.

`(close-port port)` procedure

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.

`(call-with-port port proc)` procedure

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.

### 8.2.7 Input ports

An input port allows the reading of an infinite sequence of bytes or characters punctuated by end-of-file objects. An input port connected to a finite data source ends in an infinite sequence of end-of-file objects.

It is unspecified whether a character encoding consisting of several bytes may have an end of file between the bytes. If, for example, `get-char` raises an `&i/o-decoding` exception because the character encoding at the port’s position is incomplete up to the next end of file, a subsequent call to `get-char` may successfully decode a character if bytes completing the encoding are available after the end of file.

`(input-port? obj)` procedure

Returns `#t` if the argument is an input port (or a combined input and output port), and returns `#f` otherwise.

`(port-eof? input-port)` procedure

Returns `#t` if the `lookahead-u8` procedure (if input-port is a binary port) or the `lookahead-char` procedure (if input-port is a textual port) would return the end-of-file object, and `#f` otherwise. The operation may block indefinitely if no data is available but the port cannot be determined to be at end of file.

`(open-file-input-port filename)` procedure
`(open-file-input-port filename file-options)` procedure
`(open-file-input-port filename` procedure
`file-options buffer-mode)`
`(open-file-input-port filename` procedure
`file-options buffer-mode maybe-transcoder)`

Maybe-transcoder must be either a transcoder or `#f`.

The `open-file-input-port` procedure returns an input port for the named file. The file-options and maybe-transcoder arguments are optional.

The file-options argument, which may determine various aspects of the returned port (see section 8.2.2), defaults to the value of `(file-options)`.

The buffer-mode argument, if supplied, must be one of the symbols that name a buffer mode. The buffer-mode argument defaults to `block`.

If maybe-transcoder is a transcoder, it becomes the transcoder associated with the returned port.

If maybe-transcoder is `#f` or absent, the port will be a binary port and will support the `port-position` and `set-port-position!` operations. Otherwise the port will be a textual port, and whether it supports the `port-position` and `set-port-position!` operations is implementation-dependent (and possibly transcoder-dependent).

`(open-bytevector-input-port bytevector)` procedure
`(open-bytevector-input-port bytevector` procedure
`maybe-transcoder)`

Maybe-transcoder must be either a transcoder or `#f`.

The `open-bytevector-input-port` procedure returns an input port whose bytes are drawn from bytevector. If transcoder is specified, it becomes the transcoder associated with the returned port.

If maybe-transcoder is `#f` or absent, the port will be a binary port and will support the `port-position` and `set-port-position!` operations. Otherwise the port will be a textual port, and whether it supports the `port-position` and `set-port-position!` operations will be implementation-dependent (and possibly transcoder-dependent).

If bytevector is modified after `open-bytevector-input-port` has been called, the effect on the returned port is unspecified.

`(open-string-input-port string)` procedure

Returns a textual input port whose characters are drawn from string. The port may or may not have an associated transcoder; if it does, the transcoder is implementation-dependent. The port should support the `port-position` and `set-port-position!` operations.

If string is modified after `open-string-input-port` has been called, the effect on the returned port is unspecified.

`(standard-input-port)` procedure

Returns a fresh binary input port connected to standard input. Whether the port supports the `port-position` and `set-port-position!` operations is implementation-dependent.

`(current-input-port)` procedure

This returns a default textual port for input. Normally, this default port is associated with standard input, but can be dynamically re-assigned using the `with-input-from-file` procedure from the `(rnrs io simple (6))` library (see section 8.3). The port may or may not have an associated transcoder; if it does, the transcoder is implementation-dependent.

`(make-custom-binary-input-port id read!` procedure
`
get-position set-position! close)`

Returns a newly created binary input port whose byte source is an arbitrary algorithm represented by the read! procedure. Id must be a string naming the new port, provided for informational purposes only. Read! must be a procedure and should behave as specified below; it will be called by operations that perform binary input.

Each of the remaining arguments may be `#f`; if any of those arguments is not `#f`, it must be a procedure and should behave as specified below.

- `(read! bytevector start count)`

  Start will be a non-negative exact integer object, count will be a positive exact integer object, and bytevector will be a bytevector whose length is at least start + count. The read! procedure should obtain up to count bytes from the byte source, and should write those bytes into bytevector starting at index start. The read! procedure should return an exact integer object. This integer object should represent the number of bytes that it has read. To indicate an end of file, the read! procedure should write no bytes and return 0.

- `(get-position)`

  The get-position procedure (if supplied) should return an exact integer object representing the current position of the input port. If not supplied, the custom port will not support the `port-position` operation.

- `(set-position! pos)`

  Pos will be a non-negative exact integer object. The set-position! procedure (if supplied) should set the position of the input port to pos. If not supplied, the custom port will not support the `set-port-position!` operation.

- `(close)`

  The close procedure (if supplied) should perform any actions that are necessary when the input port is closed.

Implementation responsibilities: The implementation must check the return values of read! and get-position only when it actually calls them as part of an I/O operation requested by the program. The implementation is not required to check that these procedures otherwise behave as described. If they do not, however, the behavior of the resulting port is unspecified.

`(make-custom-textual-input-port id read!` procedure
`
get-position set-position! close)`

Returns a newly created textual input port whose character source is an arbitrary algorithm represented by the read! procedure. Id must be a string naming the new port, provided for informational purposes only. Read! must be a procedure and should behave as specified below; it will be called by operations that perform textual input.

Each of the remaining arguments may be `#f`; if any of those arguments is not `#f`, it must be a procedure and should behave as specified below.

- `(read! string start count)`

  Start will be a non-negative exact integer object, count will be a positive exact integer object, and string will be a string whose length is at least start + count. The read! procedure should obtain up to count characters from the character source, and should write those characters into string starting at index start. The read! procedure should return an exact integer object representing the number of characters that it has written. To indicate an end of file, the read! procedure should write no bytes and return 0.

- `(get-position)`

  The get-position procedure (if supplied) should return a single value. The return value should represent the current position of the input port. If not supplied, the custom port will not support the `port-position` operation.

- `(set-position! pos)`

  The set-position! procedure (if supplied) should set the position of the input port to pos if pos is the return value of a call to get-position. If not supplied, the custom port will not support the `set-port-position!` operation.

- `(close)`

  The close procedure (if supplied) should perform any actions that are necessary when the input port is closed.

The port may or may not have an an associated transcoder; if it does, the transcoder is implementation-dependent.

Implementation responsibilities: The implementation must check the return values of read! and get-position only when it actually calls them as part of an I/O operation requested by the program. The implementation is not required to check that these procedures otherwise behave as described. If they do not, however, the behavior of the resulting port is unspecified.

### 8.2.8 Binary input

`(get-u8 binary-input-port)` procedure

Reads from binary-input-port, blocking as necessary, until a byte is available from binary-input-port or until an end of file is reached. If a byte becomes available, `get-u8` returns the byte as an octet and updates binary-input-port to point just past that byte. If no input byte is seen before an end of file is reached, the end-of-file object is returned.

`(lookahead-u8 binary-input-port)` procedure

The `lookahead-u8` procedure is like `get-u8`, but it does not update binary-input-port to point past the byte.

`(get-bytevector-n binary-input-port count)` procedure

Count must be an exact, non-negative integer object representing the number of bytes to be read. The `get-bytevector-n` procedure reads from binary-input-port, blocking as necessary, until count bytes are available from binary-input-port or until an end of file is reached. If count bytes are available before an end of file, `get-bytevector-n` returns a bytevector of size count. If fewer bytes are available before an end of file, `get-bytevector-n` returns a bytevector containing those bytes. In either case, the input port is updated to point just past the bytes read. If an end of file is reached before any bytes are available, `get-bytevector-n` returns the end-of-file object.

`(get-bytevector-n! binary-input-port` procedure
`
bytevector start count)`

Count must be an exact, non-negative integer object, representing the number of bytes to be read. bytevector must be a bytevector with at least start + count elements.

The `get-bytevector-n!` procedure reads from binary-input-port, blocking as necessary, until count bytes are available from binary-input-port or until an end of file is reached. If count bytes are available before an end of file, they are written into bytevector starting at index start, and the result is count. If fewer bytes are available before the next end of file, the available bytes are written into bytevector starting at index start, and the result is a number object representing the number of bytes actually read. In either case, the input port is updated to point just past the bytes read. If an end of file is reached before any bytes are available, `get-bytevector-n!` returns the end-of-file object.

`(get-bytevector-some binary-input-port)` procedure

Reads from binary-input-port, blocking as necessary, until bytes are available from binary-input-port or until an end of file is reached. If bytes become available, `get-bytevector-some` returns a freshly allocated bytevector containing the initial available bytes (at least one), and it updates binary-input-port to point just past these bytes. If no input bytes are seen before an end of file is reached, the end-of-file object is returned.

`(get-bytevector-all binary-input-port)` procedure

Attempts to read all bytes until the next end of file, blocking as necessary. If one or more bytes are read, `get-bytevector-all` returns a bytevector containing all bytes up to the next end of file. Otherwise, `get-bytevector-all` returns the end-of-file object. The operation may block indefinitely waiting to see if more bytes will become available, even if some bytes are already available.

### 8.2.9 Textual input

`(get-char textual-input-port)` procedure

Reads from textual-input-port, blocking as necessary, until a complete character is available from textual-input-port, or until an end of file is reached.

If a complete character is available before the next end of file, `get-char` returns that character and updates the input port to point past the character. If an end of file is reached before any character is read, `get-char` returns the end-of-file object.

`(lookahead-char textual-input-port)` procedure

The `lookahead-char` procedure is like `get-char`, but it does not update textual-input-port to point past the character.

> Note: With some of the standard transcoders described in this document, up to four bytes of lookahead are needed. Nonstandard transcoders may need even more lookahead.

`(get-string-n textual-input-port count)` procedure

Count must be an exact, non-negative integer object, representing the number of characters to be read.

The `get-string-n` procedure reads from textual-input-port, blocking as necessary, until count characters are available, or until an end of file is reached.

If count characters are available before end of file, `get-string-n` returns a string consisting of those count characters. If fewer characters are available before an end of file, but one or more characters can be read, `get-string-n` returns a string containing those characters. In either case, the input port is updated to point just past the characters read. If no characters can be read before an end of file, the end-of-file object is returned.

`(get-string-n! textual-input-port string start count)` procedure

Start and count must be exact, non-negative integer objects, with count representing the number of characters to be read. String must be a string with at least start + count characters.

The `get-string-n!` procedure reads from textual-input-port in the same manner as `get-string-n`. If count characters are available before an end of file, they are written into string starting at index start, and count is returned. If fewer characters are available before an end of file, but one or more can be read, those characters are written into string starting at index start and the number of characters actually read is returned as an exact integer object. If no characters can be read before an end of file, the end-of-file object is returned.

`(get-string-all textual-input-port)` procedure

Reads from textual-input-port until an end of file, decoding characters in the same manner as `get-string-n` and `get-string-n!`.

If characters are available before the end of file, a string containing all the characters decoded from that data are returned. If no character precedes the end of file, the end-of-file object is returned.

`(get-line textual-input-port)` procedure

Reads from textual-input-port up to and including the linefeed character or end of file, decoding characters in the same manner as `get-string-n` and `get-string-n!`.

If a linefeed character is read, a string containing all of the text up to (but not including) the linefeed character is returned, and the port is updated to point just past the linefeed character. If an end of file is encountered before any linefeed character is read, but some characters have been read and decoded as characters, a string containing those characters is returned. If an end of file is encountered before any characters are read, the end-of-file object is returned.

> Note: The end-of-line style, if not `none`, will cause all line endings to be read as linefeed characters. See section 8.2.4.

`(get-datum textual-input-port)` procedure

Reads an external representation from textual-input-port and returns the datum it represents. The `get-datum` procedure returns the next datum that can be parsed from the given textual-input-port, updating textual-input-port to point exactly past the end of the external representation of the object.

Any <interlexeme space> (see report section on “Lexical syntax”) in the input is first skipped. If an end of file occurs after the <interlexeme space>, the end-of-file object (see section 8.2.5) is returned.

If a character inconsistent with an external representation is encountered in the input, an exception with condition types `&lexical` and `&i/o-read` is raised. Also, if the end of file is encountered after the beginning of an external representation, but the external representation is incomplete and therefore cannot be parsed, an exception with condition types `&lexical` and `&i/o-read` is raised.

### 8.2.10 Output ports

An output port is a sink to which bytes or characters are written. The written data may control external devices or may produce files and other objects that may subsequently be opened for input.

`(output-port? obj)` procedure

Returns `#t` if the argument is an output port (or a combined input and output port), `#f` otherwise.

`(flush-output-port output-port)` procedure

Flushes any buffered output from the buffer of output-port to the underlying file, device, or object. The `flush-output-port` procedure returns unspecified values.

`(output-port-buffer-mode output-port)` procedure

Returns the symbol that represents the buffer mode of output-port.

`(open-file-output-port filename)` procedure
`(open-file-output-port filename file-options)` procedure
`(open-file-output-port filename` procedure
`file-options buffer-mode)`
`(open-file-output-port filename` procedure
`file-options buffer-mode maybe-transcoder)`

Maybe-transcoder must be either a transcoder or `#f`.

The `open-file-output-port` procedure returns an output port for the named file.

The file-options argument, which may determine various aspects of the returned port (see section 8.2.2), defaults to the value of `(file-options)`.

The buffer-mode argument, if supplied, must be one of the symbols that name a buffer mode. The buffer-mode argument defaults to `block`.

If maybe-transcoder is a transcoder, it becomes the transcoder associated with the port.

If maybe-transcoder is `#f` or absent, the port will be a binary port and will support the `port-position` and `set-port-position!` operations. Otherwise the port will be a textual port, and whether it supports the `port-position` and `set-port-position!` operations is implementation-dependent (and possibly transcoder-dependent).

`(open-bytevector-output-port)` procedure
`(open-bytevector-output-port maybe-transcoder)` procedure

Maybe-transcoder must be either a transcoder or `#f`.

The `open-bytevector-output-port` procedure returns two values: an output port and an extraction procedure. The output port accumulates the bytes written to it for later extraction by the procedure.

If maybe-transcoder is a transcoder, it becomes the transcoder associated with the port. If maybe-transcoder is `#f` or absent, the port will be a binary port and will support the `port-position` and `set-port-position!` operations. Otherwise the port will be a textual port, and whether it supports the `port-position` and `set-port-position!` operations is implementation-dependent (and possibly transcoder-dependent).

The extraction procedure takes no arguments. When called, it returns a bytevector consisting of all the port’s accumulated bytes (regardless of the port’s current position), removes the accumulated bytes from the port, and resets the port’s position.

`(call-with-bytevector-output-port proc)` procedure
`(call-with-bytevector-output-port proc` procedure
`maybe-transcoder)`

Proc must accept one argument. Maybe-transcoder must be either a transcoder or `#f`.

The `call-with-bytevector-output-port` procedure creates an output port that accumulates the bytes written to it and calls proc with that output port as an argument. Whenever proc returns, a bytevector consisting of all of the port’s accumulated bytes (regardless of the port’s current position) is returned and the port is closed.

The transcoder associated with the output port is determined as for a call to `open-bytevector-output-port`.

`(open-string-output-port)` procedure

Returns two values: a textual output port and an extraction procedure. The output port accumulates the characters written to it for later extraction by the procedure.

The port may or may not have an associated transcoder; if it does, the transcoder is implementation-dependent. The port should support the `port-position` and `set-port-position!` operations.

The extraction procedure takes no arguments. When called, it returns a string consisting of all of the port’s accumulated characters (regardless of the current position), removes the accumulated characters from the port, and resets the port’s position.

`(call-with-string-output-port proc)` procedure

Proc must accept one argument. The `call-with-string-output-port` procedure creates a textual output port that accumulates the characters written to it and calls proc with that output port as an argument. Whenever proc returns, a string consisting of all of the port’s accumulated characters (regardless of the port’s current position) is returned and the port is closed.

The port may or may not have an associated transcoder; if it does, the transcoder is implementation-dependent. The port should support the `port-position` and `set-port-position!` operations.

`(standard-output-port)` procedure
`(standard-error-port)` procedure

Returns a fresh binary output port connected to the standard output or standard error respectively. Whether the port supports the `port-position` and `set-port-position!` operations is implementation-dependent.

`(current-output-port)` procedure
`(current-error-port)` procedure

These return default textual ports for regular output and error output. Normally, these default ports are associated with standard output, and standard error, respectively. The return value of `current-output-port` can be dynamically re-assigned using the `with-output-to-file` procedure from the `(rnrs io simple (6))` library (see section 8.3). A port returned by one of these procedures may or may not have an associated transcoder; if it does, the transcoder is implementation-dependent.

`(make-custom-binary-output-port id` procedure
`
write! get-position set-position! close)`

Returns a newly created binary output port whose byte sink is an arbitrary algorithm represented by the write! procedure. Id must be a string naming the new port, provided for informational purposes only. Write! must be a procedure and should behave as specified below; it will be called by operations that perform binary output.

Each of the remaining arguments may be `#f`; if any of those arguments is not `#f`, it must be a procedure and should behave as specified in the description of `make-custom-binary-input-port`.

- `(write! bytevector start count)`

  Start and count will be non-negative exact integer objects, and bytevector will be a bytevector whose length is at least start + count. The write! procedure should write up to count bytes from bytevector starting at index start to the byte sink. If count is 0, the write! procedure should have the effect of passing an end-of-file object to the byte sink. In any case, the write! procedure should return the number of bytes that it wrote, as an exact integer object.

Implementation responsibilities: The implementation must check the return values of write! only when it actually calls write! as part of an I/O operation requested by the program. The implementation is not required to check that write! otherwise behaves as described. If it does not, however, the behavior of the resulting port is unspecified.

`(make-custom-textual-output-port id` procedure
`
write! get-position set-position! close)`

Returns a newly created textual output port whose byte sink is an arbitrary algorithm represented by the write! procedure. Id must be a string naming the new port, provided for informational purposes only. Write! must be a procedure and should behave as specified below; it will be called by operations that perform textual output.

Each of the remaining arguments may be `#f`; if any of those arguments is not `#f`, it must be a procedure and should behave as specified in the description of `make-custom-textual-input-port`.

- `(write! string start count)`

  Start and count will be non-negative exact integer objects, and string will be a string whose length is at least start + count. The write! procedure should write up to count characters from string starting at index start to the character sink. If count is 0, the write! procedure should have the effect of passing an end-of-file object to the character sink. In any case, the write! procedure should return the number of characters that it wrote, as an exact integer object.

The port may or may not have an associated transcoder; if it does, the transcoder is implementation-dependent.

Implementation responsibilities: The implementation must check the return values of write! only when it actually calls write! as part of an I/O operation requested by the program. The implementation is not required to check that write! otherwise behaves as described. If it does not, however, the behavior of the resulting port is unspecified.

### 8.2.11 Binary output

`(put-u8 binary-output-port octet)` procedure

Writes octet to the output port and returns unspecified values.

`(put-bytevector binary-output-port bytevector)` procedure
`(put-bytevector binary-output-port bytevector start)` procedure
`(put-bytevector binary-output-port` procedure
`
bytevector start count)`

Start and count must be non-negative exact integer objects that default to 0 and `(bytevector-length bytevector)` `-` start, respectively. Bytevector must have a length of at least start + count. The `put-bytevector` procedure writes the count bytes of the bytevector bytevector starting at index start to the output port. The `put-bytevector` procedure returns unspecified values.

### 8.2.12 Textual output

`(put-char textual-output-port char)` procedure

Writes char to the port. The `put-char` procedure returns unspecified values.

`(put-string textual-output-port string)` procedure
`(put-string textual-output-port string start)` procedure
`(put-string textual-output-port string start count)` procedure

Start and count must be non-negative exact integer objects. String must have a length of at least start + count. Start defaults to 0. Count defaults to `(string-length string)` `-` start. The `put-string` procedure writes the count characters of string starting at index start to the port. The `put-string` procedure returns unspecified values.

`(put-datum textual-output-port datum)` procedure

Datum should be a datum value. The `put-datum` procedure writes an external representation of datum to textual-output-port. The specific external representation is implementation-dependent. However, whenever possible, an implementation should produce a representation for which `get-datum`, when reading the representation, will return an object equal (in the sense of `equal?`) to datum.

> Note: Not all datums may allow producing an external representation for which `get-datum` will produce an object that is equal to the original. Specifically, NaNs contained in datum may make this impossible.

> Note: The `put-datum` procedure merely writes the external representation, but no trailing delimiter. If `put-datum` is used to write several subsequent external representations to an output port, care should be taken to delimit them properly so they can be read back in by subsequent calls to `get-datum`.

### 8.2.13 Input/output ports

`(open-file-input/output-port filename)` procedure
`(open-file-input/output-port filename file-options)` procedure
`(open-file-input/output-port filename` procedure
`file-options buffer-mode)`
`(open-file-input/output-port filename` procedure
`file-options buffer-mode transcoder)`

Returns a single port that is both an input port and an output port for the named file. The optional arguments default as described in the specification of `open-file-output-port`. If the input/output port supports `port-position` and/or `set-port-position!`, the same port position is used for both input and output.

`(make-custom-binary-input/output-port` procedure
`
id read! write! get-position set-position! close)`

Returns a newly created binary input/output port whose byte source and sink are arbitrary algorithms represented by the read! and write! procedures. Id must be a string naming the new port, provided for informational purposes only. Read! and write! must be procedures, and should behave as specified for the `make-custom-binary-input-port` and `make-custom-binary-output-port` procedures.

Each of the remaining arguments may be `#f`; if any of those arguments is not `#f`, it must be a procedure and should behave as specified in the description of `make-custom-binary-input-port`.

`(make-custom-textual-input/output-port` procedure
`
id read! write! get-position set-position! close)`

Returns a newly created textual input/output port whose textual source and sink are arbitrary algorithms represented by the read! and write! procedures. Id must be a string naming the new port, provided for informational purposes only. Read! and write! must be procedures, and should behave as specified for the `make-custom-textual-input-port` and `make-custom-textual-output-port` procedures.

Each of the remaining arguments may be `#f`; if any of those arguments is not `#f`, it must be a procedure and should behave as specified in the description of `make-custom-textual-input-port`.

## 8.3 Simple I/O

This section describes the `(rnrs io simple (6))`library, which provides a somewhat more convenient interface for performing textual I/O on ports. This library implements most of the I/O procedures of the previous revision of this report [8].

The ports created by the procedures of this library are textual ports associated implementation-dependent transcoders.

`(eof-object)` procedure
`(eof-object? obj)` procedure

These are the same as `eof-object` and `eof-object?` from the `(rnrs ports (6))` library.

`(call-with-input-file filename proc)` procedure
`(call-with-output-file filename proc)` procedure

Proc should accept one argument. These procedures open the file named by filename for input or for output, with no specified file options, and call proc with the obtained port as an argument. If proc returns, the port is closed automatically and the values returned by proc are returned. If proc does not return, the port is not closed automatically, unless it is possible to prove that the port will never again be used for an I/O operation.

`(input-port? obj)` procedure
`(output-port? obj)` procedure

These are the same as the `input-port?` and `output-port?` procedures in the `(rnrs io ports (6))` library.

`(current-input-port)` procedure
`(current-output-port)` procedure
`(current-error-port)` procedure

These are the same as the `current-input-port`, `current-output-port`, and `current-error-port`procedures from the `(rnrs io ports (6))` library.

`(with-input-from-file filename thunk)` procedure
`(with-output-to-file filename thunk)` procedure

Thunk must be a procedure and must accept zero arguments. The file is opened for input or output using empty file options, and thunk is called with no arguments. During the dynamic extent of the call to thunk, the obtained port is made the value returned by `current-input-port` or `current-output-port` procedures; the previous default values are reinstated when the dynamic extent is exited. When thunk returns, the port is closed automatically. The values returned by thunk are returned. If an escape procedure is used to escape back into the call to thunk after thunk is returned, the behavior is unspecified.

`(open-input-file filename)` procedure

Opens filename for input, with empty file options, and returns the obtained port.

`(open-output-file filename)` procedure

Opens filename for output, with empty file options, and returns the obtained port.

`(close-input-port input-port)` procedure
`(close-output-port output-port)` procedure

Closes input-port or output-port, respectively.

`(read-char)` procedure
`(read-char textual-input-port)` procedure

Reads from textual-input-port, blocking as necessary until a character is available from textual-input-port, or the data that are available cannot be the prefix of any valid encoding, or an end of file is reached.

If a complete character is available before the next end of file, `read-char` returns that character, and updates the input port to point past that character. If an end of file is reached before any data are read, `read-char` returns the end-of-file object.

If textual-input-port is omitted, it defaults to the value returned by `current-input-port`.

`(peek-char)` procedure
`(peek-char textual-input-port)` procedure

This is the same as `read-char`, but does not consume any data from the port.

`(read)` procedure
`(read textual-input-port)` procedure

Reads an external representation from textual-input-port and returns the datum it represents. The `read` procedure operates in the same way as `get-datum`, see section 8.2.9.

If textual-input-port is omitted, it defaults to the value returned by `current-input-port`.

`(write-char char)` procedure
`(write-char char textual-output-port)` procedure

Writes an encoding of the character char to the textual-output-port, and returns unspecified values.

If textual-output-port is omitted, it defaults to the value returned by `current-output-port`.

`(newline)` procedure
`(newline textual-output-port)` procedure

This is equivalent to using `write-char` to write `#`\`linefeed` to textual-output-port.

If textual-output-port is omitted, it defaults to the value returned by `current-output-port`.

`(display obj)` procedure
`(display obj textual-output-port)` procedure

Writes a representation of obj to the given textual-output-port. Strings that appear in the written representation are not enclosed in doublequotes, and no characters are escaped within those strings. Character objects appear in the representation as if written by `write-char` instead of by `write`. The `display` procedure returns unspecified values. The textual-output-port argument may be omitted, in which case it defaults to the value returned by `current-output-port`.

`(write obj)` procedure
`(write obj textual-output-port)` procedure

Writes the external representation of obj to textual-output-port. The `write` procedure operates in the same way as `put-datum`; see section 8.2.12.

If textual-output-port is omitted, it defaults to the value returned by `current-output-port`.