Warning: This is the manual of the legacy Guile 2.0 series. You may want to read the manual of the current stable series instead.
Next: Reading, Up: Input and Output [Contents][Index]
Sequential input/output in Scheme is represented by operations on a port. This chapter explains the operations that Guile provides for working with ports.
Ports are created by opening, for instance open-file for a file
(see File Ports). Characters can be read from an input port and
written to an output port, or both on an input/output port. A port
can be closed (see Closing) when no longer required, after which
any attempt to read or write is an error.
The formal definition of a port is very generic: an input port is simply “an object which can deliver characters on demand,” and an output port is “an object which can accept characters.” Because this definition is so loose, it is easy to write functions that simulate ports in software. Soft ports and string ports are two interesting and powerful examples of this technique. (see Soft Ports, and String Ports.)
Ports are garbage collected in the usual way (see Memory Management), and will be closed at that time if not already closed. In this case any errors occurring in the close will not be reported. Usually a program will want to explicitly close so as to be sure all its operations have been successful. Of course if a program has abandoned something due to an error or other condition then closing problems are probably not of interest.
It is strongly recommended that file ports be closed explicitly when no longer required. Most systems have limits on how many files can be open, both on a per-process and a system-wide basis. A program that uses many files should take care not to hit those limits. The same applies to similar system resources such as pipes and sockets.
Note that automatic garbage collection is triggered only by memory
consumption, not by file or other resource usage, so a program cannot
rely on that to keep it away from system limits. An explicit call to
gc can of course be relied on to pick up unreferenced ports.
If program flow makes it hard to be certain when to close then this
may be an acceptable way to control resource usage.
All file access uses the “LFS” large file support functions when available, so files bigger than 2 Gbytes (2^31 bytes) can be read and written on a 32-bit system.
Each port has an associated character encoding that controls how bytes read from the port are converted to characters and string and controls how characters and strings written to the port are converted to bytes. When ports are created, they inherit their character encoding from the current locale, but, that can be modified after the port is created.
Currently, the ports only work with non-modal encodings. Most encodings are non-modal, meaning that the conversion of bytes to a string doesn’t depend on its context: the same byte sequence will always return the same string. A couple of modal encodings are in common use, like ISO-2022-JP and ISO-2022-KR, and they are not yet supported.
Each port also has an associated conversion strategy: what to do when a Guile character can’t be converted to the port’s encoded character representation for output. There are three possible strategies: to raise an error, to replace the character with a hex escape, or to replace the character with a substitute character.
Return #t if x is an input port, otherwise return
#f. Any object satisfying this predicate also satisfies
port?.
Return #t if x is an output port, otherwise return
#f. Any object satisfying this predicate also satisfies
port?.
Return a boolean indicating whether x is a port.
Equivalent to (or (input-port? x) (output-port?
x)).
Sets the character encoding that will be used to interpret all port I/O. enc is a string containing the name of an encoding. Valid encoding names are those defined by IANA.
A fluid containing #f or the name of the encoding to
be used by default for newly created ports (see Fluids and Dynamic States). The value #f is equivalent to "ISO-8859-1".
New ports are created with the encoding appropriate for the current
locale if setlocale has been called or the value specified by
this fluid otherwise.
Returns, as a string, the character encoding that port uses to interpret
its input and output. The value #f is equivalent to "ISO-8859-1".
Sets the behavior of the interpreter when outputting a character that
is not representable in the port’s current encoding. sym can be
either 'error, 'substitute, or 'escape. If it is
'error, an error will be thrown when an nonconvertible character
is encountered. If it is 'substitute, then nonconvertible
characters will be replaced with approximate characters, or with
question marks if no approximately correct character is available. If
it is 'escape, it will appear as a hex escape when output.
If port is an open port, the conversion error behavior
is set for that port. If it is #f, it is set as the
default behavior for any future ports that get created in
this thread.
Returns the behavior of the port when outputting a character that is
not representable in the port’s current encoding. It returns the
symbol error if unrepresentable characters should cause
exceptions, substitute if the port should try to replace
unrepresentable characters with question marks or approximate
characters, or escape if unrepresentable characters should be
converted to string escapes.
If port is #f, then the current default behavior will be
returned. New ports will have this default behavior when they are
created.
The fluid that defines the conversion strategy for newly created ports,
and for other conversion routines such as scm_to_stringn,
scm_from_stringn, string->pointer, and
pointer->string.
Its value must be one of the symbols described above, with the same
semantics: 'error, 'substitute, or 'escape.
When Guile starts, its value is 'substitute.
Note that (set-port-conversion-strategy! #f sym) is
equivalent to (fluid-set! %default-port-conversion-strategy
sym).
Next: Reading, Up: Input and Output [Contents][Index]