r6rs-lib
[Go to
first
previous
next
page
contents
index
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 [
].
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
&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.
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.
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.
file-options
parameter name means that the
corresponding argument must be a file-options object.
file-options
...
syntax
Each
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
they have implementation-specific meaning, if any.
Note:
Only the name of
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
syntax
of
none
line
, and
block
. The result is the
corresponding symbol, and specifies the associated buffer mode.
Note:
Only the name of
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.
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).
transcoder
parameter name means that the corresponding
argument must be a transcoder.
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
syntax
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
cr
crlf
nel
crnel
ls
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
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
syntax
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
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
(see report section on “Lexical syntax”) in
the input is first skipped. If an end of file occurs after the
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 [
].
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
[Go to
first
previous
next
page
contents
index
US