Input and Output
================

Ports
-----

Ports are the way that Guile performs input and output.  Guile can read in characters or bytes from an input port, or write them out to an output port.  Some ports support both interfaces.

There are a number of different port types implemented in Guile.  File ports provide input and output over files, as you might imagine.  For example, we might display a string to a file like this:

     (let ((port (open-output-file "foo.txt")))
       (display "Hello, world!\n" port)
       (close-port port))

There are also string ports, for taking input from a string, or collecting output to a string; bytevector ports, for doing the same but using a bytevector as a source or sink of data; and soft ports, for arranging to call Scheme functions to provide input or handle output. See Port Types.

Ports should be closed when they are not needed by calling close-port on them, as in the example above.  This will make sure that any pending output is successfully written out to disk, in the case of a file port, or otherwise to whatever mutable store is backed by the port.  Any error that occurs while writing out that buffered data would also be raised promptly at the close-port, and not later when the port is closed by the garbage collector.  See Buffering, for more on buffered output.

Closing a port also releases any precious resource the file might have. Usually in Scheme a programmer doesn't have to clean up after their data structures (see Memory Management), but most systems have strict 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.

Indeed for these reasons the above example is not the most idiomatic way to use ports.  It is more common to acquire ports via procedures like call-with-output-file, which handle the close-port automatically:

     (call-with-output-file "foo.txt"
       (lambda (port)
         (display "Hello, world!\n" port)))

Finally, all ports have associated input and output buffers, as appropriate.  Buffering is a common strategy to limit the overhead of small reads and writes: without buffering, each character fetched from a file would involve at least one call into the kernel, and maybe more depending on the character and the encoding.  Instead, Guile will batch reads and writes into internal buffers.  However, sometimes you want to make output on a port show up immediately.  See Buffering, for more on interfaces to control port buffering.

 -- Scheme Procedure: port? x
 -- C Function: scm_port_p (x)
     Return a boolean indicating whether X is a port.

 -- 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: close-port port
 -- C Function: scm_close_port (port)
     Close the specified port object.  Return #t if it successfully closes a port or #f if it was already closed.  An exception may be raised if an error occurs, for example when flushing buffered output. See Buffering, for more on buffered output.  See close, for a procedure which can close file descriptors.

 -- Scheme Procedure: port-closed? port
 -- C Function: scm_port_closed_p (port)
     Return #t if PORT is closed or #f if it is open.

Binary I/O
----------

Guile's ports are fundamentally binary in nature: at the lowest level, they work on bytes.  This section describes Guile's core binary I/O operations.  See Textual I/O, for input and output of strings and characters.

To use these routines, first include the binary I/O module:

     (use-modules (ice-9 binary-ports))

Note that although this module's name suggests that binary ports are some different kind of port, that's not the case: all ports in Guile are both binary and textual ports.

 -- Scheme Procedure: get-u8 port
 -- C Function: scm_get_u8 (port)
     Return an octet read from PORT, an input port, blocking as necessary, or the end-of-file object.

 -- Scheme Procedure: lookahead-u8 port
 -- C Function: scm_lookahead_u8 (port)
     Like get-u8 but does not update PORT's position to point past the octet.

The end-of-file object is unlike any other kind of object: it's not a pair, a symbol, or anything else.  To check if a value is the end-of-file object, use the eof-object? predicate.

 -- Scheme Procedure: eof-object? x
 -- C Function: scm_eof_object_p (x)
     Return #t if X is an end-of-file object, or #f otherwise.

Note that unlike other procedures in this module, eof-object? is defined in the default environment.

 -- Scheme Procedure: get-bytevector-n port count
 -- C Function: scm_get_bytevector_n (port, count)
     Read COUNT octets from PORT, blocking as necessary and return a bytevector containing the octets read.  If fewer bytes are available, a bytevector smaller than COUNT is returned.

 -- Scheme Procedure: get-bytevector-n! port bv start count
 -- C Function: scm_get_bytevector_n_x (port, bv, start, count)
     Read COUNT bytes from PORT and store them in BV starting at index START.  Return either the number of bytes actually read or the end-of-file object.

 -- Scheme Procedure: get-bytevector-some port
 -- C Function: scm_get_bytevector_some (port)
     Read from PORT, blocking as necessary, until bytes are available or an end-of-file is reached.  Return either the end-of-file object or a new bytevector containing some of the available bytes (at least one), and update the port position to point just past these bytes.

 -- Scheme Procedure: get-bytevector-some! port bv start count
 -- C Function: scm_get_bytevector_some_x (port, bv, start, count)
     Read up to COUNT bytes from PORT, blocking as necessary until at least one byte is available or an end-of-file is reached. Store them in BV starting at index START.  Return the number of bytes actually read, or an end-of-file object.

 -- Scheme Procedure: get-bytevector-all port
 -- C Function: scm_get_bytevector_all (port)
     Read from PORT, blocking as necessary, until the end-of-file is reached.  Return either a new bytevector containing the data read or the end-of-file object (if no data were available).

 -- Scheme Procedure: unget-bytevector port bv [start [count]]
 -- C Function: scm_unget_bytevector (port, bv, start, count)
     Place the contents of BV in PORT, optionally starting at index START and limiting to COUNT octets, so that its bytes will be read from left-to-right as the next bytes from PORT during subsequent read operations.  If called multiple times, the unread bytes will be read again in last-in first-out order.

To perform binary output on a port, use put-u8 or put-bytevector.

 -- Scheme Procedure: put-u8 port octet
 -- C Function: scm_put_u8 (port, octet)
     Write OCTET, an integer in the 0--255 range, to PORT, a binary output port.

 -- Scheme Procedure: put-bytevector port bv [start [count]]
 -- C Function: scm_put_bytevector (port, bv, start, count)
     Write the contents of BV to PORT, optionally starting at index START and limiting to COUNT octets.

Encoding
--------

Textual input and output on Guile ports is layered on top of binary operations.  To this end, each port has an associated character encoding that controls how bytes read from the port are converted to characters, and how characters written to the port are converted to bytes.

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

 -- 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 I/O to PORT.  ENC is a string containing the name of an encoding. Valid encoding names are those defined by IANA (http://www.iana.org/assignments/character-sets), for example "UTF-8" or "ISO-8859-1".

When ports are created, they are assigned an encoding.  The usual process to determine the initial encoding for a port is to take the value of the %default-port-encoding fluid.

 -- Scheme Variable: %default-port-encoding
     A fluid containing name of the encoding to be used by default for newly created ports (see Fluids and Dynamic States).  As a special case, the value #f is equivalent to "ISO-8859-1".

The %default-port-encoding itself defaults to the encoding appropriate for the current locale, if setlocale has been called. See Locales, for more on locales and when you might need to call setlocale explicitly.

Some port types have other ways of determining their initial locales. String ports, for example, default to the UTF-8 encoding, in order to be able to represent all characters regardless of the current locale.  File ports can optionally sniff their file for a coding: declaration; see File Ports.  Binary ports might be initialized to the ISO-8859-1 encoding in which each codepoint between 0 and 255 corresponds to a byte with that value.

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, which determines 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.  Port conversion strategies are also used when decoding characters from an input port.

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

     If PORT is #f, then the current default behavior will be returned.  New ports will have this default behavior when they are created.

 -- Scheme Procedure: set-port-conversion-strategy! port sym
 -- C Function: scm_set_port_conversion_strategy_x (port, sym)
     Sets the behavior of Guile when outputting a character that is not representable in the port's current encoding, or when Guile encounters a decoding error when trying to read a character.  SYM can be either error, substitute, or escape.

     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.

As with port encodings, there is a fluid which determines the initial conversion strategy for a port.

 -- Scheme Variable: %default-port-conversion-strategy
     The fluid that defines the conversion strategy for newly created ports, and also 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).

As mentioned above, for an output port there are three possible port conversion strategies.  The error strategy will throw an error when a nonconvertible character is encountered.  The substitute strategy will replace nonconvertible characters with a question mark (?).  Finally the escape strategy will print nonconvertible characters as a hex escape, using the escaping that is recognized by Guile's string syntax.  Note that if the port's encoding is a Unicode encoding, like UTF-8, then encoding errors are impossible.

For an input port, the error strategy will cause Guile to throw an error if it encounters an invalid encoding, such as might happen if you tried to read ISO-8859-1 as UTF-8.  The error is thrown before advancing the read position.  The substitute strategy will replace the bad bytes with a U+FFFD replacement character, in accordance with Unicode recommendations.  When reading from an input port, the escape strategy is treated as if it were error.

Textual I/O
-----------

This section describes Guile's core textual I/O operations on characters and strings.  See Binary I/O, for input and output of bytes and bytevectors.  See Encoding, for more on how characters relate to bytes.  To read general S-expressions from ports, see Scheme Read. See Scheme Write, for interfaces that write generic Scheme datums.

To use these routines, first include the textual I/O module:

     (use-modules (ice-9 textual-ports))

Note that although this module's name suggests that textual ports are some different kind of port, that's not the case: all ports in Guile are both binary and textual ports.

 -- Scheme Procedure: get-char input-port
     Reads from INPUT-PORT, blocking as necessary, until a complete character is available from 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.

 -- Scheme Procedure: lookahead-char input-port
     The lookahead-char procedure is like get-char, but it does not update INPUT-PORT to point past the character.

In the same way that it's possible to "unget" a byte or bytes, it's possible to "unget" the bytes corresponding to an encoded character.

 -- Scheme Procedure: unget-char port char
     Place character CHAR in PORT so that it will be read by the next read operation.  If called multiple times, the unread characters will be read again in last-in first-out order.

 -- Scheme Procedure: unget-string port str
     Place the string STR in PORT so that its characters will be read from left-to-right as the next characters from PORT during subsequent read operations.  If called multiple times, the unread characters will be read again in last-in first-out order.

Reading in a character at a time can be inefficient.  If it's possible to perform I/O over multiple characters at a time, via strings, that might be faster.

 -- Scheme Procedure: get-string-n input-port count
     The get-string-n procedure reads from INPUT-PORT, blocking as necessary, until COUNT characters are available, or until an end of file is reached.  COUNT must be an exact, non-negative integer, representing the number of characters to be read.

     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.

 -- Scheme Procedure: get-string-n! input-port string start count
     The get-string-n! procedure reads from INPUT-PORT in the same manner as get-string-n.  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.

     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.

 -- Scheme Procedure: get-string-all input-port
     Reads from 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.

 -- Scheme Procedure: get-line input-port
     Reads from 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.

Finally, there are just two core procedures to write characters to a port.

 -- Scheme Procedure: put-char port char
     Writes CHAR to the port. The put-char procedure returns an unspecified value.

 -- Scheme Procedure: put-string port string
 -- Scheme Procedure: put-string port string start
 -- Scheme Procedure: put-string port string start count
     Write the COUNT characters of STRING starting at index START to the port.

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

     Calling put-string is equivalent in all respects to calling put-char on the relevant sequence of characters, except that it will attempt to write multiple characters to the port at a time, even if the port is unbuffered.

     The put-string procedure returns an unspecified value.

Textual ports have a textual position associated with them: a line and a column.  Reading in characters or writing them out advances the line and the column appropriately.

 -- Scheme Procedure: port-column port
 -- Scheme Procedure: port-line port
 -- C Function: scm_port_column (port)
 -- C Function: scm_port_line (port)
     Return the current column number or line number of PORT.

Port lines and positions are represented as 0-origin integers, which is to say that the the first character of the first line is line 0, column 0.  However, when you display a line number, for example in an error message, we recommend you add 1 to get 1-origin integers.  This is because lines numbers traditionally start with 1, and that is what non-programmers will find most natural.

 -- Scheme Procedure: set-port-column! port column
 -- Scheme Procedure: set-port-line! port line
 -- C Function: scm_set_port_column_x (port, column)
 -- C Function: scm_set_port_line_x (port, line)
     Set the current column or line number of PORT.

Simple Textual Output
---------------------

Guile exports a simple formatted output function, simple-format. For a more capable formatted output facility, see Formatted Output.

 -- Scheme Procedure: simple-format destination message . args
 -- C Function: scm_simple_format (destination, message, args)
     Write MESSAGE to DESTINATION, defaulting to the current output port.  MESSAGE can contain ~A and ~S escapes. When printed, the escapes are replaced with corresponding members of ARGS: ~A formats using display and ~S formats using write.  If DESTINATION is #t, then use the current output port, if DESTINATION is #f, then return a string containing the formatted text.  Does not add a trailing newline.

Somewhat confusingly, Guile binds the format identifier to simple-format at startup.  Once (ice-9 format) loads, it actually replaces the core format binding, so depending on whether you or a module you use has loaded (ice-9 format), you may be using the simple or the more capable version.

Buffering
---------

Every port has associated input and output buffers.  You can think of ports as being backed by some mutable store, and that store might be far away.  For example, ports backed by file descriptors have to go all the way to the kernel to read and write their data.  To avoid this round-trip cost, Guile usually reads in data from the mutable store in chunks, and then services small requests like get-char out of that intermediate buffer.  Similarly, small writes like write-char first go to a buffer, and are sent to the store when the buffer is full (or when port is flushed).  Buffered ports speed up your program by reducing the number of round-trips to the mutable store, and they do so in a way that is mostly transparent to the user.

There are two major ways, however, in which buffering affects program semantics.  Building correct, performant programs requires understanding these situations.

The first case is in random-access read/write ports (see Random Access).  These ports, usually backed by a file, logically operate over the same mutable store when both reading and writing.  So, if you read a character, causing the buffer to fill, then write a character, the bytes you filled in your read buffer are now invalid.  Every time you switch between reading and writing, Guile has to flush any pending buffer.  If this happens frequently, the cost can be high.  In that case you should reduce the amount that you buffer, in both directions.  Similarly, Guile has to flush buffers before seeking.  None of these considerations apply to sockets, which don't logically read from and write to the same mutable store, and are not seekable.  Note also that sockets are unbuffered by default.  See Network Sockets and Communication.

The second case is the more pernicious one.  If you write data to a buffered port, it probably doesn't go out to the mutable store directly. (This ``probably'' introduces some indeterminism in your program: what goes to the store, and when, depends on how full the buffer is.  It is something that the user needs to explicitly be aware of.)  The data is written to the store later -- when the buffer fills up due to another write, or when force-output is called, or when close-port is called, or when the program exits, or even when the garbage collector runs.  The salient point is, the errors are signalled then too. Buffered writes defer error detection (and defer the side effects to the mutable store), perhaps indefinitely if the port type does not need to be closed at GC.

One common heuristic that works well for textual ports is to flush output when a newline (\n) is written.  This line buffering mode is on by default for TTY ports.  Most other ports are block buffered, meaning that once the output buffer reaches the block size, which depends on the port and its configuration, the output is flushed as a block, without regard to what is in the block.  Likewise reads are read in at the block size, though if there are fewer bytes available to read, the buffer may not be entirely filled.

Note that binary reads or writes that are larger than the buffer size go directly to the mutable store without passing through the buffers.  If your access pattern involves many big reads or writes, buffering might not matter so much to you.

To control the buffering behavior of a port, use setvbuf.

 -- Scheme Procedure: setvbuf port mode [size]
 -- C Function: scm_setvbuf (port, mode, size)
     Set the buffering mode for PORT.  MODE can be one of the following symbols:

     none
          non-buffered

     line
          line buffered

     block
          block buffered, using a newly allocated buffer of SIZE bytes. If SIZE is omitted, a default size will be used.

Another way to set the buffering, for file ports, is to open the file with 0 or l as part of the mode string, for unbuffered or line-buffered ports, respectively.  See File Ports, for more.

Any buffered output data will be written out when the port is closed. To make sure to flush it at specific points in your program, use force-otput.

 -- Scheme Procedure: force-output [port]
 -- C Function: scm_force_output (port)
     Flush the specified output port, or the current output port if PORT is omitted.  The current output buffer contents, if any, are passed to the underlying port implementation.

     The return value is unspecified.

 -- Scheme Procedure: flush-all-ports
 -- C Function: scm_flush_all_ports ()
     Equivalent to calling force-output on all open output ports.  The return value is unspecified.

Similarly, sometimes you might want to switch from using Guile's ports to working directly on file descriptors.  In that case, for input ports use drain-input to get any buffered input from that port.

 -- Scheme Procedure: drain-input port
 -- C Function: scm_drain_input (port)
     This procedure clears a port's input buffers, similar to the way that force-output clears the output buffer.  The contents of the buffers are returned as a single string, e.g.,

          (define p (open-input-file ...))
          (drain-input p) => empty string, nothing buffered yet.
          (unread-char (read-char p) p)
          (drain-input p) => initial chars from p, up to the buffer size.

All of these considerations are very similar to those of streams in the C library, although Guile's ports are not built on top of C streams. Still, it is useful to read what other systems do. See Streams (The GNU C Library Reference Manual), for more discussion on C streams.

Random Access
-------------

 -- Scheme Procedure: seek fd_port offset whence
 -- C Function: scm_seek (fd_port, offset, whence)
     Sets the current position of FD_PORT to the integer OFFSET.  For a file port, OFFSET is expressed as a number of bytes; for other types of ports, such as string ports, OFFSET is an abstract representation of the position within the port's data, not necessarily expressed as a number of bytes.  OFFSET is interpreted according to the value of WHENCE.

     One of the following variables should be supplied for WHENCE:
      -- Variable: SEEK_SET
          Seek from the beginning of the file.

      -- Variable: SEEK_CUR
          Seek from the current position.

      -- Variable: SEEK_END
          Seek from the end of the file.

     If FD_PORT is a file descriptor, the underlying system call is lseek.  PORT may be a string port.

     The value returned is the new position in FD_PORT.  This means that the current position of a port can be obtained using:

          (seek port 0 SEEK_CUR)

 -- Scheme Procedure: ftell fd_port
 -- C Function: scm_ftell (fd_port)
     Return an integer representing the current position of FD_PORT, measured from the beginning.  Equivalent to:

          (seek port 0 SEEK_CUR)

 -- Scheme Procedure: truncate-file file [length]
 -- C Function: scm_truncate_file (file, length)
     Truncate FILE to LENGTH bytes.  FILE can be a filename string, a port object, or an integer file descriptor.  The return value is unspecified.

     For a port or file descriptor LENGTH can be omitted, in which case the file is truncated at the current position (per ftell above).

     On most systems a file can be extended by giving a length greater than the current size, but this is not mandatory in the POSIX standard.

Line Oriented and Delimited Text
--------------------------------

The delimited-I/O module can be accessed with:

     (use-modules (ice-9 rdelim))

It can be used to read or write lines of text, or read text delimited by a specified set of characters.

 -- Scheme Procedure: read-line [port] [handle-delim]
     Return a line of text from PORT if specified, otherwise from the value returned by (current-input-port).  Under Unix, a line of text is terminated by the first end-of-line character or by end-of-file.

     If HANDLE-DELIM is specified, it should be one of the following symbols:

     trim
          Discard the terminating delimiter.  This is the default, but it will be impossible to tell whether the read terminated with a delimiter or end-of-file.

     concat
          Append the terminating delimiter (if any) to the returned string.

     peek
          Push the terminating delimiter (if any) back on to the port.

     split
          Return a pair containing the string read from the port and the terminating delimiter or end-of-file object.

 -- Scheme Procedure: read-line! buf [port]
     Read a line of text into the supplied string BUF and return the number of characters added to BUF.  If BUF is filled, then #f is returned.  Read from PORT if specified, otherwise from the value returned by (current-input-port).

 -- Scheme Procedure: read-delimited delims [port] [handle-delim]
     Read text until one of the characters in the string DELIMS is found or end-of-file is reached.  Read from PORT if supplied, otherwise from the value returned by (current-input-port). HANDLE-DELIM takes the same values as described for read-line.

 -- Scheme Procedure: read-delimited! delims buf [port] [handle-delim] [start] [end]
     Read text into the supplied string BUF.

     If a delimiter was found, return the number of characters written, except if HANDLE-DELIM is split, in which case the return value is a pair, as noted above.

     As a special case, if PORT was already at end-of-stream, the EOF object is returned. Also, if no characters were written because the buffer was full, #f is returned.

     It's something of a wacky interface, to be honest.

 -- Scheme Procedure: %read-delimited! delims str gobble [port [start [end]]]
 -- C Function: scm_read_delimited_x (delims, str, gobble, port, start, end)
     Read characters from PORT into STR until one of the characters in the DELIMS string is encountered.  If GOBBLE is true, discard the delimiter character; otherwise, leave it in the input stream for the next read.  If PORT is not specified, use the value of (current-input-port).  If START or END are specified, store data only into the substring of STR bounded by START and END (which default to the beginning and end of the string, respectively).

     Return a pair consisting of the delimiter that terminated the string and the number of characters read.  If reading stopped at the end of file, the delimiter returned is the EOF-OBJECT; if the string was filled without encountering a delimiter, this value is #f.

 -- Scheme Procedure: %read-line [port]
 -- C Function: scm_read_line (port)
     Read a newline-terminated line from PORT, allocating storage as necessary.  The newline terminator (if any) is removed from the string, and a pair consisting of the line and its delimiter is returned.  The delimiter may be either a newline or the EOF-OBJECT; if %read-line is called at the end of file, it returns the pair (#<eof> . #<eof>).

Default Ports for Input, Output and Errors
------------------------------------------

 -- Scheme Procedure: current-input-port
 -- C Function: scm_current_input_port ()
     Return the current input port.  This is the default port used by many input procedures.

     Initially this is the standard input in Unix and C terminology. When the standard input is a tty the port is unbuffered, otherwise it's fully buffered.

     Unbuffered input is good if an application runs an interactive subprocess, since any type-ahead input won't go into Guile's buffer and be unavailable to the subprocess.

     Note that Guile buffering is completely separate from the tty ``line discipline''.  In the usual cooked mode on a tty Guile only sees a line of input once the user presses Return.

 -- Scheme Procedure: current-output-port
 -- C Function: scm_current_output_port ()
     Return the current output port.  This is the default port used by many output procedures.

     Initially this is the standard output in Unix and C terminology. When the standard output is a tty this port is unbuffered, otherwise it's fully buffered.

     Unbuffered output to a tty is good for ensuring progress output or a prompt is seen.  But an application which always prints whole lines could change to line buffered, or an application with a lot of output could go fully buffered and perhaps make explicit force-output calls (see Buffering) at selected points.

 -- Scheme Procedure: current-error-port
 -- C Function: scm_current_error_port ()
     Return the port to which errors and warnings should be sent.

     Initially this is the standard error in Unix and C terminology. When the standard error is a tty this port is unbuffered, otherwise it's fully buffered.

 -- Scheme Procedure: set-current-input-port port
 -- Scheme Procedure: set-current-output-port port
 -- Scheme Procedure: set-current-error-port port
 -- C Function: scm_set_current_input_port (port)
 -- C Function: scm_set_current_output_port (port)
 -- C Function: scm_set_current_error_port (port)
     Change the ports returned by current-input-port, current-output-port and current-error-port, respectively, so that they use the supplied PORT for input or output.

 -- Scheme Procedure: with-input-from-port port thunk
 -- Scheme Procedure: with-output-to-port port thunk
 -- Scheme Procedure: with-error-to-port port thunk
     Call THUNK in a dynamic environment in which current-input-port, current-output-port or current-error-port is rebound to the given PORT.

 -- C Function: void scm_dynwind_current_input_port (SCM port)
 -- C Function: void scm_dynwind_current_output_port (SCM port)
 -- C Function: void scm_dynwind_current_error_port (SCM port)
     These functions must be used inside a pair of calls to scm_dynwind_begin and scm_dynwind_end (see Dynamic Wind).  During the dynwind context, the indicated port is set to PORT.

     More precisely, the current port is swapped with a `backup' value whenever the dynwind context is entered or left.  The backup value is initialized with the PORT argument.

Types of Port
-------------

File Ports
..........

The following procedures are used to open file ports. See also open, for an interface to the Unix open system call.

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.

Most systems have limits on how many files can be open, so it's strongly recommended that file ports be closed explicitly when no longer required (see Ports).

 -- Scheme Procedure: open-file filename mode
     [#:guess-encoding=#f] [#:encoding=#f]
 -- C Function: scm_open_file_with_encoding
     (filename, mode, guess_encoding, encoding)
 -- C Function: scm_open_file (filename, mode)
     Open the file whose name is FILENAME, and return a port representing that file.  The attributes of the port are determined by the MODE string.  The way in which this is interpreted is similar to C stdio.  The first character must be one of the following:

     r
          Open an existing file for input.

     w
          Open a file for output, creating it if it doesn't already exist or removing its contents if it does.

     a
          Open a file for output, creating it if it doesn't already exist.  All writes to the port will go to the end of the file. The "append mode" can be turned off while the port is in use see fcntl

     The following additional characters can be appended:

     +
          Open the port for both input and output.  E.g., r+: open an existing file for both input and output.

     0
          Create an "unbuffered" port.  In this case input and output operations are passed directly to the underlying port implementation without additional buffering.  This is likely to slow down I/O operations.  The buffering mode can be changed while a port is in use (see Buffering).

     l
          Add line-buffering to the port.  The port output buffer will be automatically flushed whenever a newline character is written.

     b
          Use binary mode, ensuring that each byte in the file will be read as one Scheme character.

          To provide this property, the file will be opened with the 8-bit character encoding "ISO-8859-1", ignoring the default port encoding. See Ports, for more information on port encodings.

          Note that while it is possible to read and write binary data as characters or strings, it is usually better to treat bytes as octets, and byte sequences as bytevectors.  See Binary I/O, for more.

          This option had another historical meaning, for DOS compatibility: in the default (textual) mode, DOS reads a CR-LF sequence as one LF byte. The b flag prevents this from happening, adding O_BINARY to the underlying open call.  Still, the flag is generally useful because of its port encoding ramifications.

     Unless binary mode is requested, the character encoding of the new port is determined as follows: First, if GUESS-ENCODING is true, the file-encoding procedure is used to guess the encoding of the file (see Character Encoding of Source Files).  If GUESS-ENCODING is false or if file-encoding fails, ENCODING is used unless it is also false.  As a last resort, the default port encoding is used. See Ports, for more information on port encodings.  It is an error to pass a non-false GUESS-ENCODING or ENCODING if binary mode is requested.

     If a file cannot be opened with the access requested, open-file throws an exception.

 -- Scheme Procedure: open-input-file filename
     [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]

     Open FILENAME for input.  If BINARY is true, open the port in binary mode, otherwise use text mode.  ENCODING and GUESS-ENCODING determine the character encoding as described above for open-file.  Equivalent to

          (open-file FILENAME
                     (if BINARY "rb" "r")
                     #:guess-encoding GUESS-ENCODING
                     #:encoding ENCODING)

 -- Scheme Procedure: open-output-file filename
     [#:encoding=#f] [#:binary=#f]

     Open FILENAME for output.  If BINARY is true, open the port in binary mode, otherwise use text mode.  ENCODING specifies the character encoding as described above for open-file.  Equivalent to

          (open-file FILENAME
                     (if BINARY "wb" "w")
                     #:encoding ENCODING)

 -- Scheme Procedure: call-with-input-file filename proc
     [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]
 -- Scheme Procedure: call-with-output-file filename proc
     [#:encoding=#f] [#:binary=#f]
     Open FILENAME for input or output, and call (PROC port) with the resulting port.  Return the value returned by PROC.  FILENAME is opened as per open-input-file or open-output-file respectively, and an error is signaled if it cannot be opened.

     When PROC returns, the port is closed.  If PROC does not return (e.g. if it throws an error), then the port might not be closed automatically, though it will be garbage collected in the usual way if not otherwise referenced.

 -- Scheme Procedure: with-input-from-file filename thunk
     [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]
 -- Scheme Procedure: with-output-to-file filename thunk
     [#:encoding=#f] [#:binary=#f]
 -- Scheme Procedure: with-error-to-file filename thunk
     [#:encoding=#f] [#:binary=#f]
     Open FILENAME and call (THUNK) with the new port setup as respectively the current-input-port, current-output-port, or current-error-port.  Return the value returned by THUNK.  FILENAME is opened as per open-input-file or open-output-file respectively, and an error is signaled if it cannot be opened.

     When THUNK returns, the port is closed and the previous setting of the respective current port is restored.

     The current port setting is managed with dynamic-wind, so the previous value is restored no matter how THUNK exits (eg. an exception), and if THUNK is re-entered (via a captured continuation) then it's set again to the FILENAME port.

     The port is closed when THUNK returns normally, but not when exited via an exception or new continuation.  This ensures it's still ready for use if THUNK is re-entered by a captured continuation. Of course the port is always garbage collected and closed in the usual way when no longer referenced anywhere.

 -- Scheme Procedure: port-mode port
 -- C Function: scm_port_mode (port)
     Return the port modes associated with the open port PORT. These will not necessarily be identical to the modes used when the port was opened, since modes such as "append" which are used only during port creation are not retained.

 -- Scheme Procedure: port-filename port
 -- C Function: scm_port_filename (port)
     Return the filename associated with PORT, or #f if no filename is associated with the port.

     PORT must be open; port-filename cannot be used once the port is closed.

 -- Scheme Procedure: set-port-filename! port filename
 -- C Function: scm_set_port_filename_x (port, filename)
     Change the filename associated with PORT, using the current input port if none is specified.  Note that this does not change the port's source of data, but only the value that is returned by port-filename and reported in diagnostic output.

 -- Scheme Procedure: file-port? obj
 -- C Function: scm_file_port_p (obj)
     Determine whether OBJ is a port that is related to a file.

Bytevector Ports
................

 -- Scheme Procedure: open-bytevector-input-port bv [transcoder]
 -- C Function: scm_open_bytevector_input_port (bv, transcoder)
     Return an input port whose contents are drawn from bytevector BV (see Bytevectors).

     The TRANSCODER argument is currently not supported.

 -- Scheme Procedure: open-bytevector-output-port [transcoder]
 -- C Function: scm_open_bytevector_output_port (transcoder)
     Return two values: a binary output port and a procedure.  The latter should be called with zero arguments to obtain a bytevector containing the data accumulated by the port, as illustrated below.

          (call-with-values
            (lambda ()
              (open-bytevector-output-port))
            (lambda (port get-bytevector)
              (display "hello" port)
              (get-bytevector)))

          => #vu8(104 101 108 108 111)

     The TRANSCODER argument is currently not supported.

String Ports
............

 -- Scheme Procedure: call-with-output-string proc
 -- C Function: scm_call_with_output_string (proc)
     Calls the one-argument procedure PROC with a newly created output port.  When the function returns, the string composed of the characters written into the port is returned.  PROC should not close the port.

 -- Scheme Procedure: call-with-input-string string proc
 -- C Function: scm_call_with_input_string (string, proc)
     Calls the one-argument procedure PROC with a newly created input port from which STRING's contents may be read.  The value yielded by the PROC is returned.

 -- Scheme Procedure: with-output-to-string thunk
     Calls the zero-argument procedure THUNK with the current output port set temporarily to a new string port.  It returns a string composed of the characters written to the current output.

 -- Scheme Procedure: with-input-from-string string thunk
     Calls the zero-argument procedure THUNK with the current input port set temporarily to a string port opened on the specified STRING.  The value yielded by THUNK is returned.

 -- Scheme Procedure: open-input-string str
 -- C Function: scm_open_input_string (str)
     Take a string and return an input port that delivers characters from the string. The port can be closed by close-input-port, though its storage will be reclaimed by the garbage collector if it becomes inaccessible.

 -- Scheme Procedure: open-output-string
 -- C Function: scm_open_output_string ()
     Return an output port that will accumulate characters for retrieval by get-output-string. The port can be closed by the procedure close-output-port, though its storage will be reclaimed by the garbage collector if it becomes inaccessible.

 -- Scheme Procedure: get-output-string port
 -- C Function: scm_get_output_string (port)
     Given an output port created by open-output-string, return a string consisting of the characters that have been output to the port so far.

     get-output-string must be used before closing PORT, once closed the string cannot be obtained.

With string ports, the port-encoding is treated differently than other types of ports.  When string ports are created, they do not inherit a character encoding from the current locale.  They are given a default locale that allows them to handle all valid string characters. Typically one should not modify a string port's character encoding away from its default.  See Encoding.

Custom Ports
............

Custom ports allow the user to provide input and handle output via user-supplied procedures.  Guile currently only provides custom binary ports, not textual ports; for custom textual ports, see Soft Ports. We should add the R6RS custom textual port interfaces though. Contributions are appreciated.

 -- Scheme Procedure: make-custom-binary-input-port id read! get-position set-position! close
     Return a new custom binary input port (This is similar in spirit to Guile's soft ports (see Soft Ports).) named ID (a string) whose input is drained by invoking READ! and passing it a bytevector, an index where bytes should be written, and the number of bytes to read.  The read!  procedure must return an integer indicating the number of bytes read, or 0 to indicate the end-of-file.

     Optionally, if GET-POSITION is not #f, it must be a thunk that will be called when port-position is invoked on the custom binary port and should return an integer indicating the position within the underlying data stream; if GET-POSITION was not supplied, the returned port does not support port-position.

     Likewise, if SET-POSITION! is not #f, it should be a one-argument procedure.  When set-port-position! is invoked on the custom binary input port, SET-POSITION! is passed an integer indicating the position of the next byte is to read.

     Finally, if CLOSE is not #f, it must be a thunk.  It is invoked when the custom binary input port is closed.

     The returned port is fully buffered by default, but its buffering mode can be changed using setvbuf (see Buffering).

     Using a custom binary input port, the open-bytevector-input-port procedure (see Bytevector Ports) could be implemented as follows:

          (define (open-bytevector-input-port source)
            (define position 0)
            (define length (bytevector-length source))

            (define (read! bv start count)
              (let ((count (min count (- length position))))
                (bytevector-copy! source position
                                  bv start count)
                (set! position (+ position count))
                count))

            (define (get-position) position)

            (define (set-position! new-position)
              (set! position new-position))

            (make-custom-binary-input-port "the port" read!
                                            get-position set-position!
                                            #f))

          (read (open-bytevector-input-port (string->utf8 "hello")))
          => hello

 -- Scheme Procedure: make-custom-binary-output-port id write! get-position set-position! close
     Return a new custom binary output port named ID (a string) whose output is sunk by invoking WRITE! and passing it a bytevector, an index where bytes should be read from this bytevector, and the number of bytes to be ``written''.  The write!  procedure must return an integer indicating the number of bytes actually written; when it is passed 0 as the number of bytes to write, it should behave as though an end-of-file was sent to the byte sink.

     The other arguments are as for make-custom-binary-input-port.

 -- Scheme Procedure: make-custom-binary-input/output-port id read! write! get-position set-position! close
     Return a new custom binary input/output port named ID (a string). The various arguments are the same as for The other arguments are as for make-custom-binary-input-port and make-custom-binary-output-port.  If buffering is enabled on the port, as is the case by default, input will be buffered in both directions; see Buffering.  If the SET-POSITION! function is provided and not #f, then the port will also be marked as random-access, causing the buffer to be flushed between reads and writes.

Soft Ports
..........

A soft port is a port based on a vector of procedures capable of accepting or delivering characters.  It allows emulation of I/O ports.

 -- Scheme Procedure: make-soft-port pv modes
     Return a port capable of receiving or delivering characters as specified by the MODES string (see open-file).  PV must be a vector of length 5 or 6.  Its components are as follows:

      0. procedure accepting one character for output

      1. procedure accepting a string for output

      2. thunk for flushing output

      3. thunk for getting one character

      4. thunk for closing port (not by garbage collection)

      5. (if present and not #f) thunk for computing the number of characters that can be read from the port without blocking.

     For an output-only port only elements 0, 1, 2, and 4 need be procedures.  For an input-only port only elements 3 and 4 need be procedures.  Thunks 2 and 4 can instead be #f if there is no useful operation for them to perform.

     If thunk 3 returns #f or an eof-object (see eof-object? (The Revised^5 Report on Scheme)) it indicates that the port has reached end-of-file. For example:

          (define stdout (current-output-port))
          (define p (make-soft-port
                     (vector
                      (lambda (c) (write c stdout))
                      (lambda (s) (display s stdout))
                      (lambda () (display "." stdout))
                      (lambda () (char-upcase (read-char)))
                      (lambda () (display "@" stdout)))
                     "rw"))

          (write p p) => #<input-output: soft 8081e20>

Void Ports
..........

This kind of port causes any data to be discarded when written to, and always returns the end-of-file object when read from.

 -- Scheme Procedure: %make-void-port mode
 -- C Function: scm_sys_make_void_port (mode)
     Create and return a new void port.  A void port acts like /dev/null.  The MODE argument specifies the input/output modes for this port: see the documentation for open-file in File Ports.

Venerable Port Interfaces
-------------------------

Over the 25 years or so that Guile has been around, its port system has evolved, adding many useful features.  At the same time there have been four major Scheme standards released in those 25 years, which also evolve the common Scheme understanding of what a port interface should be.  Alas, it would be too much to ask for all of these evolutionary branches to be consistent.  Some of Guile's original interfaces don't mesh with the later Scheme standards, and yet Guile can't just drop old interfaces.  Sadly as well, the R6RS and R7RS standards both part from a base of R5RS, but end up in different and somewhat incompatible designs.

Guile's approach is to pick a set of port primitives that make sense together.  We document that set of primitives, design our internal interfaces around them, and recommend them to users.  As the R6RS I/O system is the most capable standard that Scheme has yet produced in this domain, we mostly recommend that; (ice-9 binary-ports) and (ice-9 textual-ports) are wholly modelled on (rnrs io ports).  Guile does not wholly copy R6RS, however; see R6RS Incompatibilities.

At the same time, we have many venerable port interfaces, lore handed down to us from our hacker ancestors.  Most of these interfaces even predate the expectation that Scheme should have modules, so they are present in the default environment.  In Guile we support them as well and we have no plans to remove them, but again we don't recommend them for new users.

 -- Scheme Procedure: char-ready? [port]
     Return #t if a character is ready on input PORT and return #f otherwise.  If char-ready? returns #t then the next read-char operation on PORT is guaranteed not to hang.  If PORT is a file port at end of file then char-ready? returns #t.

     char-ready? exists to make it possible for a program to accept characters from interactive ports without getting stuck waiting for input.  Any input editors associated with such ports must make sure that characters whose existence has been asserted by char-ready? cannot be rubbed out. If char-ready? were to return #f at end of file, a port at end of file would be indistinguishable from an interactive port that has no ready characters.

     Note that char-ready? only works reliably for terminals and sockets with one-byte encodings.  Under the hood it will return #t if the port has any input buffered, or if the file descriptor that backs the port polls as readable, indicating that Guile can fetch more bytes from the kernel.  However being able to fetch one byte doesn't mean that a full character is available; see Encoding.  Also, on many systems it's possible for a file descriptor to poll as readable, but then block when it comes time to read bytes.  Note also that on Linux kernels, all file ports backed by files always poll as readable. For non-file ports, this procedure always returns #t, except for soft ports, which have a char-ready? handler.  See Soft Ports.

     In short, this is a legacy procedure whose semantics are hard to provide.  However it is a useful check to see if any input is buffered. See Non-Blocking I/O.

 -- Scheme Procedure: read-char [port]
     The same as get-char, except that PORT defaults to the current input port.  See Textual I/O.

 -- Scheme Procedure: peek-char [port]
     The same as lookahead-char, except that PORT defaults to the current input port.  See Textual I/O.

 -- Scheme Procedure: unread-char cobj [port]
     The same as unget-char, except that PORT defaults to the current input port, and the arguments are swapped.  See Textual I/O.

 -- Scheme Procedure: unread-string str port
 -- C Function: scm_unread_string (str, port)
     The same as unget-string, except that PORT defaults to the current input port, and the arguments are swapped.  See Textual I/O.

 -- Scheme Procedure: newline [port]
     Send a newline to PORT.  If PORT is omitted, send to the current output port.  Equivalent to (put-char port #\newline).

 -- Scheme Procedure: write-char chr [port]
     The same as put-char, except that PORT defaults to the current input port, and the arguments are swapped.  See Textual I/O.

Using Ports from C
------------------

Guile's C interfaces provides some niceties for sending and receiving bytes and characters in a way that works better with C.

 -- C Function: size_t scm_c_read (SCM port, void *buffer, size_t size)
     Read up to SIZE bytes from PORT and store them in BUFFER.  The return value is the number of bytes actually read, which can be less than SIZE if end-of-file has been reached.

     Note that as this is a binary input procedure, this function does not update port-line and port-column (see Textual I/O).

 -- C Function: void scm_c_write (SCM port, const void *buffer, size_t size)
     Write SIZE bytes at BUFFER to PORT.

     Note that as this is a binary output procedure, this function does not update port-line and port-column (see Textual I/O).

 -- C Function: size_t scm_c_read_bytes (SCM port, SCM bv, size_t start, size_t count)
 -- C Function: void scm_c_write_bytes (SCM port, SCM bv, size_t start, size_t count)
     Like scm_c_read and scm_c_write, but reading into or writing from the bytevector BV.  COUNT indicates the byte index at which to start in the bytevector, and the read or write will continue for COUNT bytes.

 -- C Function: void scm_unget_bytes (const unsigned char *buf, size_t len, SCM port)
 -- C Function: void scm_unget_byte (int c, SCM port)
 -- C Function: void scm_ungetc (scm_t_wchar c, SCM port)
     Like unget-bytevector, unget-byte, and unget-char, respectively.  See Textual I/O.

 -- C Function: void scm_c_put_latin1_chars (SCM port, const scm_t_uint8 *buf, size_t len)
 -- C Function: void scm_c_put_utf32_chars (SCM port, const scm_t_uint32 *buf, size_t len);
     Write a string to PORT.  In the first case, the scm_t_uint8* buffer is a string in the latin-1 encoding.  In the second, the scm_t_uint32* buffer is a string in the UTF-32 encoding.  These routines will update the port's line and column.

Implementing New Port Types in C
--------------------------------

This section describes how to implement a new port type in C.  Although ports support many operations, as a data structure they present an opaque interface to the user.  To the port implementor, you have two pieces of information to work with: the port type, and the port's ``stream''.  The port type is an opaque pointer allocated when defining your port type.  It is your key into the port API, and it helps you identify which ports are actually yours.  The ``stream'' is a pointer you control, and which you set when you create a port.  Get a stream from a port using the SCM_STREAM macro.  Note that your port methods are only ever called with ports of your type.

A port type is created by calling scm_make_port_type.  Once you have your port type, you can create ports with scm_c_make_port, or scm_c_make_port_with_encoding.

 -- Function: scm_t_port_type* scm_make_port_type (char *name, size_t (*read) (SCM port, SCM dst, size_t start, size_t count), size_t (*write) (SCM port, SCM src, size_t start, size_t count))
     Define a new port type.  The NAME, READ and WRITE parameters are initial values for those port type fields, as described below.  The other fields are initialized with default values and can be changed later.

 -- Function: SCM scm_c_make_port_with_encoding (scm_t_port_type *type, unsigned long mode_bits, SCM encoding, SCM conversion_strategy, scm_t_bits stream)
 -- Function: SCM scm_c_make_port (scm_t_port_type *type, unsigned long mode_bits, scm_t_bits stream)
     Make a port with the given TYPE.  The STREAM indicates the private data associated with the port, which your port implementation may later retrieve with SCM_STREAM.  The mode bits should include one or more of the flags SCM_RDNG or SCM_WRTNG, indicating that the port is an input and/or an output port, respectively.  The mode bits may also include SCM_BUF0 or SCM_BUFLINE, indicating that the port should be unbuffered or line-buffered, respectively.  The default is that the port will be block-buffered.  See Buffering.

     As you would imagine, ENCODING and CONVERSION_STRATEGY specify the port's initial textual encoding and conversion strategy. Both are symbols.  scm_c_make_port is the same as scm_c_make_port_with_encoding, except it uses the default port encoding and conversion strategy.

The port type has a number of associate procedures and properties which collectively implement the port's behavior.  Creating a new port type mostly involves writing these procedures.

name
     A pointer to a NUL terminated string: the name of the port type.  This property is initialized via the first argument to scm_make_port_type.

read
     A port's read implementation fills read buffers.  It should copy bytes to the supplied bytevector dst, starting at offset start and continuing for count bytes, returning the number of bytes read.

write
     A port's write implementation flushes write buffers to the mutable store.  A port's read implementation fills read buffers. It should write out bytes from the supplied bytevector src, starting at offset start and continuing for count bytes, and return the number of bytes that were written.

read_wait_fd
write_wait_fd
     If a port's read or write function returns (size_t) -1, that indicates that reading or writing would block.  In that case to preserve the illusion of a blocking read or write operation, Guile's C port run-time will poll on the file descriptor returned by either the port's read_wait_fd or write_wait_fd function. Set using

      -- Function: void scm_set_port_read_wait_fd (scm_t_port_type *type, int (*wait_fd) (SCM port))
      -- Function: void scm_set_port_write_wait_fd (scm_t_port_type *type, int (*wait_fd) (SCM port))

     Only a port type which implements the read_wait_fd or write_wait_fd port methods can usefully return (size_t) -1 from a read or write function.  See Non-Blocking I/O, for more on non-blocking I/O in Guile.

print
     Called when write is called on the port, to print a port description.  For example, for a file port it may produce something like: #<input: /etc/passwd 3>.  Set using

      -- Function: void scm_set_port_print (scm_t_port_type *type, int (*print) (SCM port, SCM dest_port, scm_print_state *pstate))
          The first argument PORT is the port being printed, the second argument DEST_PORT is where its description should go.

close
     Called when the port is closed.  It should free any resources used by the port.  Set using

      -- Function: void scm_set_port_close (scm_t_port_type *type, void (*close) (SCM port))

     By default, ports that are garbage collected just go away without closing.  If your port type needs to release some external resource like a file descriptor, or needs to make sure that its internal buffers are flushed even if the port is collected while it was open, then mark the port type as needing a close on GC.

      -- Function: void scm_set_port_needs_close_on_gc (scm_t_port_type *type, int needs_close_p)

seek
     Set the current position of the port.  Guile will flush read and/or write buffers before seeking, as appropriate.

      -- Function: void scm_set_port_seek (scm_t_port_type *type, scm_t_off (*seek) (SCM port, scm_t_off offset, int whence))

truncate
     Truncate the port data to be specified length.  Guile will flush buffers before hand, as appropriate.  Set using

      -- Function: void scm_set_port_truncate (scm_t_port_type *type, void (*truncate) (SCM port, scm_t_off length))

random_access_p
     Determine whether this port is a random-access port.

     Seeking on a random-access port with buffered input, or switching to writing after reading, will cause the buffered input to be discarded and Guile will seek the port back the buffered number of bytes.  Likewise seeking on a random-access port with buffered output, or switching to reading after writing, will flush pending bytes with a call to the write procedure.  See Buffering.

     Indicate to Guile that your port needs this behavior by returning a nonzero value from your random_access_p function.  The default implementation of this function returns nonzero if the port type supplies a seek implementation.

      -- Function: void scm_set_port_random_access_p (scm_t_port_type *type, int (*random_access_p) (SCM port));

get_natural_buffer_sizes
     Guile will internally attach buffers to ports.  An input port always has a read buffer and an output port always has a write buffer. See Buffering.  A port buffer consists of a bytevector, along with some cursors into that bytevector denoting where to get and put data.

     Port implementations generally don't have to be concerned with buffering: a port type's read or write function will receive the buffer's bytevector as an argument, along with an offset and a length into that bytevector, and should then either fill or empty that bytevector.  However in some cases, port implementations may be able to provide an appropriate default buffer size to Guile.

      -- Function: void scm_set_port_get_natural_buffer_sizes
          (scm_t_port_type *type, void (*get_natural_buffer_sizes) (SCM, size_t *read_buf_size, size_t *write_buf_size))
          Fill in READ_BUF_SIZE and WRITE_BUF_SIZE with an appropriate buffer size for this port, if one is known.

     File ports implement a get_natural_buffer_sizes to let the operating system inform Guile about the appropriate buffer sizes for the particular file opened by the port.

Note that calls to all of these methods can proceed in parallel and concurrently and from any thread up until the point that the port is closed.  The call to close will happen when no other method is running, and no method will be called after the close method is called.  If your port implementation needs mutual exclusion to prevent concurrency, it is responsible for locking appropriately.

Non-Blocking I/O
----------------

Most ports in Guile are blocking: when you try to read a character from a port, Guile will block on the read until a character is ready, or end-of-stream is detected.  Likewise whenever Guile goes to write (possibly buffered) data to an output port, Guile will block until all the data is written.

Interacting with ports in blocking mode is very convenient: you can write straightforward, sequential algorithms whose code flow reflects the flow of data.  However, blocking I/O has two main limitations.

The first is that it's easy to get into a situation where code is waiting on data.  Time spent waiting on data when code could be doing something else is wasteful and prevents your program from reaching its peak throughput.  If you implement a web server that sequentially handles requests from clients, it's very easy for the server to end up waiting on a client to finish its HTTP request, or waiting on it to consume the response.  The end result is that you are able to serve fewer requests per second than you'd like to serve.

The second limitation is related: a blocking parser over user-controlled input is a denial-of-service vulnerability.  Indeed the so-called ``slow loris'' attack of the early 2010s was just that: an attack on common web servers that drip-fed HTTP requests, one character at a time.  All it took was a handful of slow loris connections to occupy an entire web server.

In Guile we would like to preserve the ability to write straightforward blocking networking processes of all kinds, but under the hood to allow those processes to suspend their requests if they would block.

To do this, the first piece is to allow Guile ports to declare themselves as being nonblocking.  This is currently supported only for file ports, which also includes sockets, terminals, or any other port that is backed by a file descriptor.  To do that, we use an arcane UNIX incantation:

     (let ((flags (fcntl socket F_GETFL)))
       (fcntl socket F_SETFL (logior O_NONBLOCK flags)))

Now the file descriptor is open in non-blocking mode.  If Guile tries to read or write from this file and the read or write returns a result indicating that more data can only be had by doing a blocking read or write, Guile will block by polling on the socket's read-wait-fd or write-wait-fd, to preserve the illusion of a blocking read or write.  See I/O Extensions for more on those internal interfaces.

So far we have just reproduced the status quo: the file descriptor is non-blocking, but the operations on the port do block.  To go farther, it would be nice if we could suspend the ``thread'' using delimited continuations, and only resume the thread once the file descriptor is readable or writable.  (see Prompts).

But here we run into a difficulty.  The ports code is implemented in C, which means that although we can suspend the computation to some outer prompt, we can't resume it because Guile can't resume delimited continuations that capture the C stack.

To overcome this difficulty we have created a compatible but entirely parallel implementation of port operations.  To use this implementation, do the following:

     (use-modules (ice-9 suspendable-ports))
     (install-suspendable-ports!)

This will replace the core I/O primitives like get-char and put-bytevector with new versions that are exactly the same as the ones in the standard library, but with two differences.  One is that when a read or a write would block, the suspendable port operations call out the value of the current-read-waiter or current-write-waiter parameter, as appropriate. See Parameters.  The default read and write waiters do the same thing that the C read and write waiters do, which is to poll.  User code can parameterize the waiters, though, enabling the computation to suspend and allow the program to process other I/O operations.  Because the new suspendable ports implementation is written in Scheme, that suspended computation can resume again later when it is able to make progress. Success!

The other main difference is that because the new ports implementation is written in Scheme, it is slower than C, currently by a factor of 3 or 4, though it depends on many factors.  For this reason we have to keep the C implementations as the default ones.  One day when Guile's compiler is better, we can close this gap and have only one port operation implementation again.

Note that Guile does not currently include an implementation of the facility to suspend the current thread and schedule other threads in the meantime.  Before adding such a thing, we want to make sure that we're providing the right primitives that can be used to build schedulers and other user-space concurrency patterns, and that the patterns that we settle on are the right patterns.  In the meantime, have a look at 8sync (https://gnu.org/software/8sync) for a prototype of an asynchronous I/O and concurrency facility.

 -- Scheme Procedure: install-suspendable-ports!
     Replace the core ports implementation with suspendable ports, as described above.  This will mutate the values of the bindings like get-char, put-u8, and so on in place.

 -- Scheme Procedure: uninstall-suspendable-ports!
     Restore the original core ports implementation, un-doing the effect of install-suspendable-ports!.

 -- Scheme Parameter: current-read-waiter
 -- Scheme Parameter: current-write-waiter
     Parameters whose values are procedures of one argument, called when a suspendable port operation would block on a port while reading or writing, respectively.  The default values of these parameters do a blocking poll on the port's file descriptor.  The procedures are passed the port in question as their one argument.

Handling of Unicode Byte Order Marks
------------------------------------

This section documents the finer points of Guile's handling of Unicode byte order marks (BOMs).  A byte order mark (U+FEFF) is typically found at the start of a UTF-16 or UTF-32 stream, to allow readers to reliably determine the byte order.  Occasionally, a BOM is found at the start of a UTF-8 stream, but this is much less common and not generally recommended.

Guile attempts to handle BOMs automatically, and in accordance with the recommendations of the Unicode Standard, when the port encoding is set to UTF-8, UTF-16, or UTF-32.  In brief, Guile automatically writes a BOM at the start of a UTF-16 or UTF-32 stream, and automatically consumes one from the start of a UTF-8, UTF-16, or UTF-32 stream.

As specified in the Unicode Standard, a BOM is only handled specially at the start of a stream, and only if the port encoding is set to UTF-8, UTF-16 or UTF-32.  If the port encoding is set to UTF-16BE, UTF-16LE, UTF-32BE, or UTF-32LE, then BOMs are not handled specially, and none of the special handling described in this section applies.

  * To ensure that Guile will properly detect the byte order of a UTF-16 or UTF-32 stream, you must perform a textual read before any writes, seeks, or binary I/O.  Guile will not attempt to read a BOM unless a read is explicitly requested at the start of the stream.

  * If a textual write is performed before the first read, then an arbitrary byte order will be chosen.  Currently, big endian is the default on all platforms, but that may change in the future.  If you wish to explicitly control the byte order of an output stream, set the port encoding to UTF-16BE, UTF-16LE, UTF-32BE, or UTF-32LE, and explicitly write a BOM (#\xFEFF) if desired.

  * If set-port-encoding! is called in the middle of a stream, Guile treats this as a new logical ``start of stream'' for purposes of BOM handling, and will forget about any BOMs that had previously been seen. Therefore, it may choose a different byte order than had been used previously.  This is intended to support multiple logical text streams embedded within a larger binary stream.

  * Binary I/O operations are not guaranteed to update Guile's notion of whether the port is at the ``start of the stream'', nor are they guaranteed to produce or consume BOMs.

  * For ports that support seeking (e.g. normal files), the input and output streams are considered linked: if the user reads first, then a BOM will be consumed (if appropriate), but later writes will not produce a BOM.  Similarly, if the user writes first, then later reads will not consume a BOM.

  * For ports that are not random access (e.g. pipes, sockets, and terminals), the input and output streams are considered independent for purposes of BOM handling: the first read will consume a BOM (if appropriate), and the first write will also produce a BOM (if appropriate).  However, the input and output streams will always use the same byte order.

  * Seeks to the beginning of a file will set the ``start of stream'' flags. Therefore, a subsequent textual read or write will consume or produce a BOM.  However, unlike set-port-encoding!, if a byte order had already been chosen for the port, it will remain in effect after a seek, and cannot be changed by the presence of a BOM.  Seeks anywhere other than the beginning of a file clear the ``start of stream'' flags.