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: , Up: Input and Output   [Contents][Index]

6.14.1 Ports

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.

Scheme Procedure: input-port? x
C Function: scm_input_port_p (x)

Return #t if x is an input port, otherwise return #f. Any object satisfying this predicate also satisfies port?.

Scheme Procedure: output-port? x
C Function: scm_output_port_p (x)

Return #t if x is an output port, otherwise return #f. Any object satisfying this predicate also satisfies port?.

Scheme Procedure: port? x
C Function: scm_port_p (x)

Return a boolean indicating whether x is a port. Equivalent to (or (input-port? x) (output-port? x)).

Scheme Procedure: set-port-encoding! port enc
C Function: scm_set_port_encoding_x (port, enc)

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.

Scheme Variable: %default-port-encoding

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.

Scheme Procedure: port-encoding port
C Function: scm_port_encoding (port)

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

Scheme Procedure: set-port-conversion-strategy! port sym
C Function: scm_set_port_conversion_strategy_x (port, sym)

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.

Scheme Procedure: port-conversion-strategy port
C Function: scm_port_conversion_strategy (port)

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.

Scheme Variable: %default-port-conversion-strategy

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: , Up: Input and Output   [Contents][Index]