[Guile-commits] 05/10: Big ports documentation update

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit a21f6467acdbd80de811574c8e7959c215adea2a
Author: Andy Wingo <address@hidden>
Date:   Wed Jun 8 10:19:27 2016 +0200

    Big ports documentation update
    
    * doc/ref/api-io.texi: Update to document ports more thoroughly.  Still
      some work needed.
    
    * doc/ref/r6rs.texi: Move ports documentation back to r6rs.texi, now
      that Guile has a more thorough binary/textual I/O story, heavily based
      on R6RS.
    
    * doc/ref/api-control.texi:
    * doc/ref/api-data.texi:
    * doc/ref/api-options.texi:
    * doc/ref/misc-modules.texi:
    * doc/ref/posix.texi:
    * doc/ref/srfi-modules.texi: Update references.
---
 doc/ref/api-control.texi  |    4 +-
 doc/ref/api-data.texi     |    4 +-
 doc/ref/api-io.texi       | 1932 ++++++++++++++++-----------------------------
 doc/ref/api-options.texi  |    2 +-
 doc/ref/misc-modules.texi |   35 +-
 doc/ref/posix.texi        |    6 +-
 doc/ref/r6rs.texi         |  566 ++++++++++++-
 doc/ref/srfi-modules.texi |    4 +-
 8 files changed, 1262 insertions(+), 1291 deletions(-)

diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index 4253a20..a1eacd6 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -1801,8 +1801,8 @@ In @code{scm_wrong_type_arg_msg}, @var{expected} is a C 
string
 describing the type of argument that was expected.
 
 In @code{scm_misc_error}, @var{message} is the error message string,
-possibly containing @code{simple-format} escapes (@pxref{Writing}), and
-the corresponding arguments in the @var{args} list.
+possibly containing @code{simple-format} escapes (@pxref{Simple
+Output}), and the corresponding arguments in the @var{args} list.
 @end deftypefn
 
 
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index 3a3a8e4..aee0bb6 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -4611,8 +4611,8 @@ they do not need to be quoted:
 @result{} #vu8(1 53 204)
 @end lisp
 
-Bytevectors can be used with the binary input/output primitives of the
-R6RS (@pxref{R6RS I/O Ports}).
+Bytevectors can be used with the binary input/output primitives
+(@pxref{Binary I/O}).
 
 @menu
 * Bytevector Endianness::       Dealing with byte order.
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 5c6c213..c0518d7 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -8,16 +8,18 @@
 @section Input and Output
 
 @menu
-* Ports::                       The idea of the port abstraction.
-* Reading::                     Procedures for reading from a port.
-* Writing::                     Procedures for writing to a port.
-* Closing::                     Procedures to close a port.
+* Ports::                       What's a port?
+* Binary I/O::                  Reading and writing bytes.
+* Encoding::                    Characters as bytes.
+* Textual I/O::                 Reading and writing characters.
+* Simple Output::               Simple syntactic sugar solution.
 * Buffering::                   Controlling when data is written to ports.
 * Random Access::               Moving around a random access port.
 * Line/Delimited::              Read and write lines or delimited text.
 * Default Ports::               Defaults for input, output and errors.
 * Port Types::                  Types of port and how to make them.
-* R6RS I/O Ports::              The R6RS port API.
+* Venerable Port Interfaces::   Procedures from the last millenium.
+* Using Ports from C::          Nice interfaces for C.
 * I/O Extensions::              Implementing new port types in C.
 * Non-Blocking I/O::            How Guile deals with EWOULDBLOCK.
 * BOM Handling::                Handling of Unicode byte order marks.
@@ -28,67 +30,53 @@
 @subsection Ports
 @cindex Port
 
-Sequential input/output in Scheme is represented by operations on a
address@hidden  This chapter explains the operations that Guile provides
-for working with ports.
-
-Ports are created by opening, for instance @code{open-file} for a file
-(@pxref{File Ports}).  Other kinds of ports include @dfn{soft ports} and
address@hidden ports} (@pxref{Soft Ports}, and @ref{String Ports}).
-Characters or bytes 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
-(@pxref{Closing}) when no longer required, after which any attempt to
-read or write is an error.
-
-Ports are garbage collected in the usual way (@pxref{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, including any buffered writes
-(@pxref{Buffering}).  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
address@hidden 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.
+Ports are the way that Guile performs input and output.  Guile can read
+in characters or bytes from an @dfn{input port}, or write them out to an
address@hidden port}.  Some ports support both interfaces.
 
-All file access uses the ``LFS'' large file support functions when
-available, so files bigger than 2 Gbytes (@math{2^31} bytes) can be
-read and written on a 32-bit system.
+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:
 
-Each port has an associated character encoding that controls how bytes
-read from the port are converted to characters and controls how
-characters 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.
address@hidden
+(let ((port (open-output-file "foo.txt")))
+  (display "Hello, world!\n" port)
+  (close-port port))
address@hidden example
 
-Currently, the ports only work with @emph{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.
+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.
address@hidden Types}.
+
+Ports should be @dfn{closed} when they are not needed by calling
address@hidden 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 @code{close-port}, and not later when the
+port is closed by the garbage collector.  @xref{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 (@pxref{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
address@hidden, which handle the @code{close-port}
+automatically:
 
address@hidden port conversion strategy
address@hidden conversion strategy, port
address@hidden decoding error
address@hidden encoding error
-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.
address@hidden
+(call-with-output-file "foo.txt"
+  (lambda (port)
+    (display "Hello, world!\n" port)))
address@hidden example
 
 Finally, all ports have associated input and output buffers, as
 appropriate.  Buffering is a common strategy to limit the overhead of
@@ -99,6 +87,11 @@ reads and writes into internal buffers.  However, sometimes 
you want to
 make output on a port show up immediately.  @xref{Buffering}, for more
 on interfaces to control port buffering.
 
address@hidden {Scheme Procedure} port? x
address@hidden {C Function} scm_port_p (x)
+Return a boolean indicating whether @var{x} is a port.
address@hidden deffn
+
 @rnindex input-port?
 @deffn {Scheme Procedure} input-port? x
 @deffnx {C Function} scm_input_port_p (x)
@@ -115,66 +108,188 @@ Return @code{#t} if @var{x} is an output port, otherwise 
return
 @code{port?}.
 @end deffn
 
address@hidden {Scheme Procedure} port? x
address@hidden {C Function} scm_port_p (x)
-Return a boolean indicating whether @var{x} is a port.
-Equivalent to @code{(or (input-port? @var{x}) (output-port?
address@hidden))}.
address@hidden Closing ports
address@hidden Port, close
address@hidden {Scheme Procedure} close-port port
address@hidden {C Function} scm_close_port (port)
+Close the specified port object.  Return @code{#t} if it successfully
+closes a port or @code{#f} if it was already closed.  An exception may
+be raised if an error occurs, for example when flushing buffered output.
address@hidden, for more on buffered output.  See also @ref{Ports and
+File Descriptors, close}, for a procedure which can close file
+descriptors.
 @end deffn
 
address@hidden {Scheme Procedure} set-port-encoding! port enc
address@hidden {C Function} scm_set_port_encoding_x (port, enc)
-Sets the character encoding that will be used to interpret all port I/O.
address@hidden is a string containing the name of an encoding.  Valid
-encoding names are those
address@hidden://www.iana.org/assignments/character-sets, defined by IANA}.
address@hidden {Scheme Procedure} port-closed? port
address@hidden {C Function} scm_port_closed_p (port)
+Return @code{#t} if @var{port} is closed or @code{#f} if it is
+open.
 @end deffn
 
address@hidden {Scheme Variable} %default-port-encoding
-A fluid containing @code{#f} or the name of the encoding to
-be used by default for newly created ports (@pxref{Fluids and Dynamic
-States}).  The value @code{#f} is equivalent to @code{"ISO-8859-1"}.
 
-New ports are created with the encoding appropriate for the current
-locale if @code{setlocale} has been called or the value specified by
-this fluid otherwise.
address@hidden defvr
address@hidden Binary I/O
address@hidden 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.  @xref{Textual I/O}, for input and output of strings and
+characters.
+
+To use these routines, first include the binary I/O module:
+
address@hidden
+(use-modules (ice-9 binary-ports))
address@hidden example
+
+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.
+
address@hidden binary input
address@hidden {Scheme Procedure} get-u8 port
address@hidden {C Function} scm_get_u8 (port)
+Return an octet read from @var{port}, an input port, blocking as
+necessary, or the end-of-file object.
address@hidden deffn
+
address@hidden {Scheme Procedure} lookahead-u8 port
address@hidden {C Function} scm_lookahead_u8 (port)
+Like @code{get-u8} but does not update @var{port}'s position to point
+past the octet.
address@hidden deffn
+
+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 @code{eof-object?} predicate.
+
address@hidden eof-object?
address@hidden End of file object
address@hidden {Scheme Procedure} eof-object? x
address@hidden {C Function} scm_eof_object_p (x)
+Return @code{#t} if @var{x} is an end-of-file object, or @code{#f}
+otherwise.
address@hidden deffn
+
+Note that unlike other procedures in this module, @code{eof-object?} is
+defined in the default environment.
+
address@hidden {Scheme Procedure} get-bytevector-n port count
address@hidden {C Function} scm_get_bytevector_n (port, count)
+Read @var{count} octets from @var{port}, blocking as necessary and
+return a bytevector containing the octets read.  If fewer bytes are
+available, a bytevector smaller than @var{count} is returned.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-bytevector-n! port bv start count
address@hidden {C Function} scm_get_bytevector_n_x (port, bv, start, count)
+Read @var{count} bytes from @var{port} and store them in @var{bv}
+starting at index @var{start}.  Return either the number of bytes
+actually read or the end-of-file object.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-bytevector-some port
address@hidden {C Function} scm_get_bytevector_some (port)
+Read from @var{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.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-bytevector-all port
address@hidden {C Function} scm_get_bytevector_all (port)
+Read from @var{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).
address@hidden deffn
+
address@hidden {Scheme Procedure} unget-bytevector port bv [start [count]]
address@hidden {C Function} scm_unget_bytevector (port, bv, start, count)
+Place the contents of @var{bv} in @var{port}, optionally starting at
+index @var{start} and limiting to @var{count} octets, so that its bytes
+will be read from left-to-right as the next bytes from @var{port} during
+subsequent read operations.  If called multiple times, the unread bytes
+will be read again in last-in first-out order.
address@hidden deffn
+
address@hidden binary output
+To perform binary output on a port, use @code{put-u8} or
address@hidden
+
address@hidden {Scheme Procedure} put-u8 port octet
address@hidden {C Function} scm_put_u8 (port, octet)
+Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
+binary output port.
address@hidden deffn
+
address@hidden {Scheme Procedure} put-bytevector port bv [start [count]]
address@hidden {C Function} scm_put_bytevector (port, bv, start, count)
+Write the contents of @var{bv} to @var{port}, optionally starting at
+index @var{start} and limiting to @var{count} octets.
address@hidden deffn
+
address@hidden Encoding
address@hidden 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.
 
 @deffn {Scheme Procedure} port-encoding port
 @deffnx {C Function} scm_port_encoding (port)
-Returns, as a string, the character encoding that @var{port} uses to interpret
-its input and output.  The value @code{#f} is equivalent to 
@code{"ISO-8859-1"}.
+Returns, as a string, the character encoding that @var{port} uses to
+interpret its input and output.
 @end deffn
 
address@hidden {Scheme Procedure} set-port-conversion-strategy! port sym
address@hidden {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.  @var{sym} can be either
address@hidden, @code{substitute}, or @code{escape}.
-
-If @var{port} is an open port, the conversion error behavior
-is set for that port.  If it is @code{#f}, it is set as the
-default behavior for any future ports that get created in
-this thread.
address@hidden {Scheme Procedure} set-port-encoding! port enc
address@hidden {C Function} scm_set_port_encoding_x (port, enc)
+Sets the character encoding that will be used to interpret I/O to
address@hidden  @var{enc} is a string containing the name of an encoding.
+Valid encoding names are those
address@hidden://www.iana.org/assignments/character-sets, defined by IANA},
+for example @code{"UTF-8"} or @code{"ISO-8859-1"}.
 @end deffn
 
-For an output port, a there are three possible port conversion
-strategies.  The @code{error} strategy will throw an error when a
-nonconvertible character is encountered.  The @code{substitute} strategy
-will replace nonconvertible characters with a question mark (@samp{?}).
-Finally the @code{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
address@hidden, then encoding errors are impossible.
+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 @code{%default-port-encoding} fluid.
 
-For an input port, the @code{error} strategy will cause Guile to throw
-an error if it encounters an invalid encoding, such as might happen if
-you tried to read @code{ISO-8859-1} as @code{UTF-8}.  The error is
-thrown before advancing the read position.  The @code{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 @code{escape} strategy is treated as if it were @code{error}.
address@hidden {Scheme Variable} %default-port-encoding
+A fluid containing name of the encoding to be used by default for newly
+created ports (@pxref{Fluids and Dynamic States}).  As a special case,
+the value @code{#f} is equivalent to @code{"ISO-8859-1"}.
address@hidden defvr
+
+The @code{%default-port-encoding} itself defaults to the encoding
+appropriate for the current locale, if @code{setlocale} has been called.
address@hidden, for more on locales and when you might need to call
address@hidden 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 @code{coding:} declaration;
address@hidden 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 @emph{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.
+
address@hidden port conversion strategy
address@hidden conversion strategy, port
address@hidden decoding error
address@hidden encoding error
+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.
 
 @deffn {Scheme Procedure} port-conversion-strategy port
 @deffnx {C Function} scm_port_conversion_strategy (port)
@@ -186,9 +301,24 @@ returned.  New ports will have this default behavior when 
they are
 created.
 @end deffn
 
address@hidden {Scheme Procedure} set-port-conversion-strategy! port sym
address@hidden {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.  @var{sym} can be either
address@hidden, @code{substitute}, or @code{escape}.
+
+If @var{port} is an open port, the conversion error behavior is set for
+that port.  If it is @code{#f}, it is set as the default behavior for
+any future ports that get created in this thread.
address@hidden deffn
+
+As with port encodings, there is a fluid which determines the initial
+conversion strategy for a port.
+
 @deffn {Scheme Variable} %default-port-conversion-strategy
 The fluid that defines the conversion strategy for newly created ports,
-and for other conversion routines such as @code{scm_to_stringn},
+and also for other conversion routines such as @code{scm_to_stringn},
 @code{scm_from_stringn}, @code{string->pointer}, and
 @code{pointer->string}.
 
@@ -202,114 +332,161 @@ equivalent to @code{(fluid-set! 
%default-port-conversion-strategy
 @var{sym})}.
 @end deffn
 
+As mentioned above, for an output port there are three possible port
+conversion strategies.  The @code{error} strategy will throw an error
+when a nonconvertible character is encountered.  The @code{substitute}
+strategy will replace nonconvertible characters with a question mark
+(@samp{?}).  Finally the @code{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 @code{UTF-8}, then encoding errors are
+impossible.
 
address@hidden Reading
address@hidden Reading
address@hidden Reading
-
-These procedures pertain to reading characters and strings from
-ports. To read general S-expressions from ports, @xref{Scheme Read}.
+For an input port, the @code{error} strategy will cause Guile to throw
+an error if it encounters an invalid encoding, such as might happen if
+you tried to read @code{ISO-8859-1} as @code{UTF-8}.  The error is
+thrown before advancing the read position.  The @code{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 @code{escape} strategy is treated as if it were @code{error}.
 
address@hidden eof-object?
address@hidden End of file object
address@hidden {Scheme Procedure} eof-object? x
address@hidden {C Function} scm_eof_object_p (x)
-Return @code{#t} if @var{x} is an end-of-file object; otherwise
-return @code{#f}.
address@hidden deffn
 
address@hidden char-ready?
address@hidden {Scheme Procedure} char-ready? [port]
address@hidden {C Function} scm_char_ready_p (port)
-Return @code{#t} if a character is ready on input @var{port}
-and return @code{#f} otherwise.  If @code{char-ready?} returns
address@hidden then the next @code{read-char} operation on
address@hidden is guaranteed not to hang.  If @var{port} is a file
-port at end of file then @code{char-ready?} returns @code{#t}.
address@hidden Textual I/O
address@hidden Textual I/O
address@hidden textual input
address@hidden textual output
 
address@hidden 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 @code{char-ready?} cannot be rubbed out.
-If @code{char-ready?} were to return @code{#f} at end of file,
-a port at end of file would be indistinguishable from an
-interactive port that has no ready characters.
address@hidden deffn
+This section describes Guile's core textual I/O operations on characters
+and strings.  @xref{Binary I/O}, for input and output of bytes and
+bytevectors.  @xref{Encoding}, for more on how characters relate to
+bytes.  To read general S-expressions from ports, @xref{Scheme Read}.
address@hidden Write}, for interfaces that write generic Scheme datums.
 
address@hidden read-char
address@hidden {Scheme Procedure} read-char [port]
address@hidden {C Function} scm_read_char (port)
-Return the next character available from @var{port}, updating @var{port}
-to point to the following character.  If no more characters are
-available, the end-of-file object is returned.  A decoding error, if
-any, is handled in accordance with the port's conversion strategy.
address@hidden deffn
+To use these routines, first include the textual I/O module:
 
address@hidden {C Function} size_t scm_c_read (SCM port, void *buffer, size_t 
size)
-Read up to @var{size} bytes from @var{port} and store them in
address@hidden  The return value is the number of bytes actually read,
-which can be less than @var{size} if end-of-file has been reached.
address@hidden
+(use-modules (ice-9 textual-ports))
address@hidden example
 
-Note that this function does not update @code{port-line} and
address@hidden below.
address@hidden deftypefn
+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.
 
address@hidden peek-char
address@hidden {Scheme Procedure} peek-char [port]
address@hidden {C Function} scm_peek_char (port)
-Return the next character available from @var{port},
address@hidden updating @var{port} to point to the following
-character.  If no more characters are available, the
-end-of-file object is returned.
address@hidden {Scheme Procedure} get-char input-port
+Reads from @var{input-port}, blocking as necessary, until a
+complete character is available from @var{input-port},
+or until an end of file is reached.
 
-The value returned by
-a call to @code{peek-char} is the same as the value that would
-have been returned by a call to @code{read-char} on the same
-port.  The only difference is that the very next call to
address@hidden or @code{peek-char} on that @var{port} will
-return the value returned by the preceding call to
address@hidden  In particular, a call to @code{peek-char} on
-an interactive port will hang waiting for input whenever a call
-to @code{read-char} would have hung.
+If a complete character is available before the next end of file,
address@hidden 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, @code{get-char} returns the end-of-file object.
address@hidden deffn
 
-As for @code{read-char}, decoding errors are handled in accordance with
-the port's conversion strategy.
address@hidden {Scheme Procedure} lookahead-char input-port
+The @code{lookahead-char} procedure is like @code{get-char}, but it does
+not update @var{input-port} to point past the character.
 @end deffn
 
address@hidden {Scheme Procedure} unread-char cobj [port]
address@hidden {C Function} scm_unread_char (cobj, port)
-Place character @var{cobj} in @var{port} so that it will be read by the
+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.
+
address@hidden {Scheme Procedure} unget-char port char
+Place character @var{char} in @var{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.  If @var{port} is
-not supplied, the current input port is used.
+will be read again in last-in first-out order.
 @end deffn
 
address@hidden {Scheme Procedure} unread-string str port
address@hidden {C Function} scm_unread_string (str, port)
address@hidden {Scheme Procedure} unget-string port str
 Place the string @var{str} in @var{port} so that its characters will
 be read from left-to-right as the next characters from @var{port}
 during subsequent read operations.  If called multiple times, the
-unread characters will be read again in last-in first-out order.  If
address@hidden is not supplied, the @code{current-input-port} is used.
+unread characters will be read again in last-in first-out order.
 @end deffn
 
address@hidden {Scheme Procedure} drain-input port
address@hidden {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.,
+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.
 
address@hidden
-(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.
address@hidden lisp
address@hidden {Scheme Procedure} get-string-n input-port count
+The @code{get-string-n} procedure reads from @var{input-port}, blocking
+as necessary, until @var{count} characters are available, or until an
+end of file is reached.  @var{count} must be an exact, non-negative
+integer, representing the number of characters to be read.
+
+If @var{count} characters are available before end of file,
address@hidden returns a string consisting of those @var{count}
+characters. If fewer characters are available before an end of file, but
+one or more characters can be read, @code{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.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-string-n! input-port string start count
+The @code{get-string-n!} procedure reads from @var{input-port} in the
+same manner as @code{get-string-n}.  @var{start} and @var{count} must be
+exact, non-negative integer objects, with @var{count} representing the
+number of characters to be read.  @var{string} must be a string with at
+least address@hidden + @var{count}$ characters.
+
+If @var{count} characters are available before an end of file, they are
+written into @var{string} starting at index @var{start}, and @var{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
address@hidden starting at index @var{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.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-string-all input-port
+Reads from @var{input-port} until an end of file, decoding characters in
+the same manner as @code{get-string-n} and @code{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.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-line input-port
+Reads from @var{input-port} up to and including the linefeed
+character or end of file, decoding characters in the same manner as
address@hidden and @code{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.
address@hidden deffn
+
+Finally, there are just two core procedures to write characters to a
+port.
 
-Draining the buffers may be useful for cleanly finishing
-buffered I/O so that the file descriptor can be used directly
-for further input.
address@hidden {Scheme Procedure} put-char port char
+Writes @var{char} to the port. The @code{put-char} procedure returns
+an unspecified value.
address@hidden deffn
+
address@hidden {Scheme Procedure} put-string port string
address@hidden {Scheme Procedure} put-string port string start
address@hidden {Scheme Procedure} put-string port string start count
+Write the @var{count} characters of @var{string} starting at index
address@hidden to the port.
+
address@hidden and @var{count} must be non-negative exact integer objects.
address@hidden must have a length of at least @address@hidden +
address@hidden  @var{start} defaults to 0.  @var{count} defaults to
address@hidden@code{(string-length @var{string})} - @var{start}}$.
+
+Calling @code{put-string} is equivalent in all respects to calling
address@hidden 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 @code{put-string} procedure returns an unspecified value.
 @end deffn
 
 @deffn {Scheme Procedure} port-column port
@@ -333,34 +510,8 @@ what non-programmers will find most natural.)
 Set the current column or line number of @var{port}.
 @end deffn
 
address@hidden Writing
address@hidden Writing
address@hidden Writing
-
-These procedures are for writing characters and strings to
-ports. For more information on writing arbitrary Scheme objects to
-ports, @xref{Scheme Write}.
-
address@hidden {Scheme Procedure} get-print-state port
address@hidden {C Function} scm_get_print_state (port)
-Return the print state of the port @var{port}.  If @var{port}
-has no associated print state, @code{#f} is returned.
address@hidden deffn
-
address@hidden newline
address@hidden {Scheme Procedure} newline [port]
address@hidden {C Function} scm_newline (port)
-Send a newline to @var{port}.
-If @var{port} is omitted, send to the current output port.
address@hidden deffn
-
address@hidden {Scheme Procedure} port-with-print-state port [pstate]
address@hidden {C Function} scm_port_with_print_state (port, pstate)
-Create a new port which behaves like @var{port}, but with an
-included print state @var{pstate}.  @var{pstate} is optional.
-If @var{pstate} isn't supplied and @var{port} already has
-a print state, the old print state is reused.
address@hidden deffn
address@hidden Simple Output
address@hidden Simple Textual Output
 
 @deffn {Scheme Procedure} simple-format destination message . args
 @deffnx {C Function} scm_simple_format (destination, message, args)
@@ -373,81 +524,7 @@ current output port, if @var{destination} is @code{#f}, 
then return a
 string containing the formatted text.  Does not add a trailing newline.
 @end deffn
 
address@hidden write-char
address@hidden {Scheme Procedure} write-char chr [port]
address@hidden {C Function} scm_write_char (chr, port)
-Send character @var{chr} to @var{port}.
address@hidden deffn
-
address@hidden {C Function} void scm_c_write (SCM port, const void *buffer, 
size_t size)
-Write @var{size} bytes at @var{buffer} to @var{port}.
-
-Note that this function does not update @code{port-line} and
address@hidden (@pxref{Reading}).
address@hidden deftypefn
-
address@hidden {C Function} void scm_lfwrite (const char *buffer, size_t size, 
SCM port)
-Write @var{size} bytes at @var{buffer} to @var{port}.  The @code{lf}
-indicates that unlike @code{scm_c_write}, this function updates the
-port's @code{port-line} and @code{port-column}, and also flushes the
-port if the data contains a newline (@code{\n}) and the port is
-line-buffered.
address@hidden deftypefn
-
address@hidden fflush
address@hidden {Scheme Procedure} force-output [port]
address@hidden {C Function} scm_force_output (port)
-Flush the specified output port, or the current output port if @var{port}
-is omitted.  The current output buffer contents are passed to the
-underlying port implementation (e.g., in the case of fports, the
-data will be written to the file and the output buffer will be cleared.)
-It has no effect on an unbuffered port.
-
-The return value is unspecified.
address@hidden deffn
-
address@hidden {Scheme Procedure} flush-all-ports
address@hidden {C Function} scm_flush_all_ports ()
-Equivalent to calling @code{force-output} on
-all open output ports.  The return value is unspecified.
address@hidden deffn
-
-
address@hidden Closing
address@hidden Closing
address@hidden Closing ports
address@hidden Port, close
-
address@hidden {Scheme Procedure} close-port port
address@hidden {C Function} scm_close_port (port)
-Close the specified port object.  Return @code{#t} if it successfully
-closes a port or @code{#f} if it was already closed.  An exception may
-be raised if an error occurs, for example when flushing buffered output.
address@hidden, for more on buffered output.  See also @ref{Ports and
-File Descriptors, close}, for a procedure which can close file
-descriptors.
address@hidden deffn
-
address@hidden {Scheme Procedure} close-input-port port
address@hidden {Scheme Procedure} close-output-port port
address@hidden {C Function} scm_close_input_port (port)
address@hidden {C Function} scm_close_output_port (port)
address@hidden close-input-port
address@hidden close-output-port
-Close the specified input or output @var{port}.  An exception may be
-raised if an error occurs while closing.  If @var{port} is already
-closed, nothing is done.  The return value is unspecified.
-
-See also @ref{Ports and File Descriptors, close}, for a procedure
-which can close file descriptors.
address@hidden deffn
-
address@hidden {Scheme Procedure} port-closed? port
address@hidden {C Function} scm_port_closed_p (port)
-Return @code{#t} if @var{port} is closed or @code{#f} if it is
-open.
address@hidden deffn
-
+pk / peek
 
 @node Buffering
 @subsection Buffering
@@ -463,7 +540,7 @@ that intermediate buffer.  Similarly, small writes like
 @code{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 the do so in a way that is mostly transparent to the user.
+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
@@ -483,7 +560,7 @@ mutable store, and are not seekable.  Note also that 
sockets are
 unbuffered by default.  @xref{Network Sockets and Communication}.
 
 The second case is the more pernicious one.  If you write data to a
-buffered port, it probably hasn't gone out to the mutable store yet.
+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
@@ -532,6 +609,44 @@ Another way to set the buffering, for file ports, is to 
open the file
 with @code{0} or @code{l} as part of the mode string, for unbuffered or
 line-buffered ports, respectively.  @xref{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
address@hidden
+
address@hidden fflush
address@hidden {Scheme Procedure} force-output [port]
address@hidden {C Function} scm_force_output (port)
+Flush the specified output port, or the current output port if
address@hidden is omitted.  The current output buffer contents, if any, are
+passed to the underlying port implementation.
+
+The return value is unspecified.
address@hidden deffn
+
address@hidden {Scheme Procedure} flush-all-ports
address@hidden {C Function} scm_flush_all_ports ()
+Equivalent to calling @code{force-output} on all open output ports.  The
+return value is unspecified.
address@hidden deffn
+
+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 @code{drain-input} to get any buffered input from that port.
+
address@hidden {Scheme Procedure} drain-input port
address@hidden {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.,
+
address@hidden
+(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.
address@hidden lisp
address@hidden deffn
+
 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.
@@ -783,7 +898,7 @@ 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 @code{force-output}
-calls (@pxref{Writing}) at selected points.
+calls (@pxref{Buffering}) at selected points.
 @end deffn
 
 @deffn {Scheme Procedure} current-error-port
@@ -827,8 +942,10 @@ initialized with the @var{port} argument.
 
 @menu
 * File Ports:: Ports on an operating system file.
+* Bytevector Ports:: Ports on a bytevector.
 * String Ports:: Ports on a Scheme string.
-* Soft Ports:: Ports on arbitrary Scheme procedures.
+* Custom Ports:: Ports whose implementation you control.
+* Soft Ports:: An older version of custom ports.
 * Void Ports:: Ports on nothing at all.
 @end menu
 
@@ -842,6 +959,10 @@ The following procedures are used to open file ports.
 See also @ref{Ports and File Descriptors, open}, for an interface
 to the Unix @code{open} system call.
 
+All file access uses the ``LFS'' large file support functions when
+available, so files bigger than 2 Gbytes (@math{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 (@pxref{Ports}).
@@ -895,8 +1016,7 @@ character encoding "ISO-8859-1", ignoring the default port 
encoding.
 
 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.  @xref{R6RS Binary Input}, and
address@hidden Binary Output}, for more.
+and byte sequences as bytevectors.  @xref{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.
@@ -1029,6 +1149,98 @@ Determine whether @var{obj} is a port that is related to 
a file.
 @end deffn
 
 
address@hidden Bytevector Ports
address@hidden Bytevector Ports
+
address@hidden {Scheme Procedure} open-bytevector-input-port bv [transcoder]
address@hidden {C Function} scm_open_bytevector_input_port (bv, transcoder)
+Return an input port whose contents are drawn from bytevector @var{bv}
+(@pxref{Bytevectors}).
+
address@hidden FIXME: Update description when implemented.
+The @var{transcoder} argument is currently not supported.
address@hidden deffn
+
address@hidden custom binary input ports
+
address@hidden {Scheme Procedure} make-custom-binary-input-port id read! 
get-position set-position! close
address@hidden {C Function} scm_make_custom_binary_input_port (id, read!, 
get-position, set-position!, close)
+Return a new custom binary input address@hidden is similar in spirit
+to Guile's @dfn{soft ports} (@pxref{Soft Ports}).} named @var{id} (a
+string) whose input is drained by invoking @var{read!} and passing it a
+bytevector, an index where bytes should be written, and the number of
+bytes to read.  The @code{read!}  procedure must return an integer
+indicating the number of bytes read, or @code{0} to indicate the
+end-of-file.
+
+Optionally, if @var{get-position} is not @code{#f}, it must be a thunk
+that will be called when @code{port-position} is invoked on the custom
+binary port and should return an integer indicating the position within
+the underlying data stream; if @var{get-position} was not supplied, the
+returned port does not support @code{port-position}.
+
+Likewise, if @var{set-position!} is not @code{#f}, it should be a
+one-argument procedure.  When @code{set-port-position!} is invoked on the
+custom binary input port, @var{set-position!} is passed an integer
+indicating the position of the next byte is to read.
+
+Finally, if @var{close} is not @code{#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 @code{setvbuf} (@pxref{Buffering}).
+
+Using a custom binary input port, the @code{open-bytevector-input-port}
+procedure could be implemented as follows:
+
address@hidden
+(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!))
+
+(read (open-bytevector-input-port (string->utf8 "hello")))
address@hidden hello
address@hidden lisp
address@hidden deffn
+
address@hidden {Scheme Procedure} open-bytevector-output-port [transcoder]
address@hidden {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.
+
address@hidden
+(call-with-values
+  (lambda ()
+    (open-bytevector-output-port))
+  (lambda (port get-bytevector)
+    (display "hello" port)
+    (get-bytevector)))
+
address@hidden #vu8(104 101 108 108 111)
address@hidden lisp
+
address@hidden FIXME: Update description when implemented.
+The @var{transcoder} argument is currently not supported.
address@hidden deffn
+
+
 @node String Ports
 @subsubsection String Ports
 @cindex String port
@@ -1103,13 +1315,90 @@ E.g., seeking and truncating will work on a string port,
 but trying to extract the file descriptor number will fail.
 
 
address@hidden Soft Ports
address@hidden Soft Ports
address@hidden Soft port
address@hidden Port, soft
address@hidden Custom Ports
address@hidden Custom Ports
 
-A @dfn{soft-port} is a port based on a vector of procedures capable of
-accepting or delivering characters.  It allows emulation of I/O ports.
+(ice-9 binary-ports), binary and text...
+
address@hidden custom binary input ports
address@hidden {Scheme Procedure} make-custom-binary-input-port id read! 
get-position set-position! close
address@hidden {C Function} scm_make_custom_binary_input_port (id, read!, 
get-position, set-position!, close)
+Return a new custom binary input address@hidden is similar in spirit
+to Guile's @dfn{soft ports} (@pxref{Soft Ports}).} named @var{id} (a
+string) whose input is drained by invoking @var{read!} and passing it a
+bytevector, an index where bytes should be written, and the number of
+bytes to read.  The @code{read!}  procedure must return an integer
+indicating the number of bytes read, or @code{0} to indicate the
+end-of-file.
+
+Optionally, if @var{get-position} is not @code{#f}, it must be a thunk
+that will be called when @code{port-position} is invoked on the custom
+binary port and should return an integer indicating the position within
+the underlying data stream; if @var{get-position} was not supplied, the
+returned port does not support @code{port-position}.
+
+Likewise, if @var{set-position!} is not @code{#f}, it should be a
+one-argument procedure.  When @code{set-port-position!} is invoked on the
+custom binary input port, @var{set-position!} is passed an integer
+indicating the position of the next byte is to read.
+
+Finally, if @var{close} is not @code{#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 @code{setvbuf} (@pxref{Buffering}).
+
+Using a custom binary input port, the @code{open-bytevector-input-port}
+procedure (@pxref{Bytevector Ports}) could be implemented as follows:
+
address@hidden
+(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!))
+
+(read (open-bytevector-input-port (string->utf8 "hello")))
address@hidden hello
address@hidden lisp
address@hidden deffn
+
address@hidden custom binary output ports
address@hidden {Scheme Procedure} make-custom-binary-output-port id write! 
get-position set-position! close
address@hidden {C Function} scm_make_custom_binary_output_port (id, write!, 
get-position, set-position!, close)
+Return a new custom binary output port named @var{id} (a string) whose
+output is sunk by invoking @var{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 @code{write!}  procedure must return an
+integer indicating the number of bytes actually written; when it is
+passed @code{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 @code{make-custom-binary-input-port}.
address@hidden deffn
+
+
address@hidden Soft Ports
address@hidden Soft Ports
address@hidden Soft port
address@hidden Port, soft
+
+A @dfn{soft-port} is a port based on a vector of procedures capable of
+accepting or delivering characters.  It allows emulation of I/O ports.
 
 @deffn {Scheme Procedure} make-soft-port pv modes
 @deffnx {C Function} scm_make_soft_port (pv, modes)
@@ -1177,962 +1466,115 @@ documentation for @code{open-file} in @ref{File 
Ports}.
 @end deffn
 
 
address@hidden R6RS I/O Ports
address@hidden R6RS I/O Ports
-
address@hidden R6RS
address@hidden R6RS ports
-
-The I/O port API of the @uref{http://www.r6rs.org/, Revised Report^6 on
-the Algorithmic Language Scheme (R6RS)} is provided by the @code{(rnrs
-io ports)} module.  It provides features, such as binary I/O and Unicode
-string I/O, that complement or refine Guile's historical port API
-presented above (@pxref{Input and Output}). Note that R6RS ports are not
-disjoint from Guile's native ports, so Guile-specific procedures will
-work on ports created using the R6RS API, and vice versa.
-
-The text in this section is taken from the R6RS standard libraries
-document, with only minor adaptions for inclusion in this manual.  The
-Guile developers offer their thanks to the R6RS editors for having
-provided the report's text under permissive conditions making this
-possible.
-
address@hidden FIXME: Update description when implemented.
address@hidden: The implementation of this R6RS API is not complete yet.
-
address@hidden
-* R6RS File Names::             File names.
-* R6RS File Options::           Options for opening files.
-* R6RS Buffer Modes::           Influencing buffering behavior.
-* R6RS Transcoders::            Influencing port encoding.
-* R6RS End-of-File::            The end-of-file object.
-* R6RS Port Manipulation::      Manipulating R6RS ports.
-* R6RS Input Ports::            Input Ports.
-* R6RS Binary Input::           Binary input.
-* R6RS Textual Input::          Textual input.
-* R6RS Output Ports::           Output Ports.
-* R6RS Binary Output::          Binary output.
-* R6RS Textual Output::         Textual output.
address@hidden menu
-
-A subset of the @code{(rnrs io ports)} module, plus one non-standard
-procedure @code{unget-bytevector} (@pxref{R6RS Binary Input}), is
-provided by the @code{(ice-9 binary-ports)} module.  It contains binary
-input/output procedures and does not rely on R6RS support.
-
address@hidden R6RS File Names
address@hidden 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 file system paths on an implementation's
-underlying operating system, and may include implementation-dependent
-values as well.
-
-A @var{filename} parameter name means that the
-corresponding argument must be a file name.
-
address@hidden R6RS File Options
address@hidden File Options
address@hidden file options
-
-When opening a file, the various procedures in this library accept a
address@hidden object that encapsulates flags to specify how the
-file is to be opened. A @code{file-options} object is an enum-set
-(@pxref{rnrs enums}) over the symbols constituting valid file options.
-
-A @var{file-options} parameter name means that the corresponding
-argument must be a file-options object.
-
address@hidden {Scheme Syntax} file-options @var{file-options-symbol} ...
-
-Each @var{file-options-symbol} must be a symbol.
-
-The @code{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 @code{(file-options)} specifies that the
-file is created if it does not exist and an exception with condition
-type @code{&i/o-file-already-exists} is raised if it does exist.  The
-following standard options can be included to modify the default
-behavior.
-
address@hidden @code
address@hidden no-create
-      If the file does not already exist, it is not created;
-      instead, an exception with condition type @code{&i/o-file-does-not-exist}
-      is raised.
-      If the file already exists, the exception with condition type
-      @code{&i/o-file-already-exists} is not raised
-      and the file is truncated to zero length.
address@hidden no-fail
-      If the file already exists, the exception with condition type
-      @code{&i/o-file-already-exists} is not raised,
-      even if @code{no-create} is not included,
-      and the file is truncated to zero length.
address@hidden no-truncate
-      If the file already exists and the exception with condition type
-      @code{&i/o-file-already-exists} has been inhibited by inclusion of
-      @code{no-create} or @code{no-fail}, the file is not truncated, but
-      the port's current position is still set to the beginning of the
-      file.
address@hidden table
-
-These options have no effect when a file is opened only for input.
-Symbols other than those listed above may be used as
address@hidden; they have implementation-specific meaning,
-if any.
-
address@hidden Note
-  Only the name of @var{file-options-symbol} is significant.
address@hidden quotation
address@hidden deffn
-
address@hidden R6RS Buffer Modes
address@hidden 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 @code{none} for no buffering,
address@hidden for flushing upon line endings and reading up to line
-endings, or other implementation-dependent behavior,
-and @code{block} for arbitrary buffering.  This section uses
-the parameter name @var{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.
-
address@hidden {Scheme Syntax} buffer-mode @var{buffer-mode-symbol}
-
address@hidden must be a symbol whose name is one of
address@hidden, @code{line}, and @code{block}. The result is the
-corresponding symbol, and specifies the associated buffer mode.
-
address@hidden Note
-  Only the name of @var{buffer-mode-symbol} is significant.
address@hidden quotation
address@hidden deffn
-
address@hidden {Scheme Procedure} buffer-mode?  obj
-Returns @code{#t} if the argument is a valid buffer-mode symbol, and
-returns @code{#f} otherwise.
address@hidden deffn
-
address@hidden R6RS Transcoders
address@hidden Transcoders
address@hidden codec
address@hidden end-of-line style
address@hidden transcoder
address@hidden binary port
address@hidden textual port
-
-Several different Unicode encoding schemes describe standard ways to
-encode characters and strings as byte sequences and to decode those
-sequences. Within this document, a @dfn{codec} is an immutable Scheme
-object that represents a Unicode or similar encoding scheme.
-
-An @dfn{end-of-line style} is a symbol that, if it is not @code{none},
-describes how a textual port transcodes representations of line endings.
-
-A @dfn{transcoder} is an immutable Scheme object that combines a codec
-with an end-of-line style and a method for handling decoding errors.
-Each transcoder represents some specific bidirectional (but not
-necessarily lossless), possibly stateful translation between byte
-sequences and Unicode characters and strings.  Every transcoder can
-operate in the input direction (bytes to characters) or in the output
-direction (characters to bytes).  A @var{transcoder} parameter name
-means that the corresponding argument must be a transcoder.
-
-A @dfn{binary port} is a port that supports binary I/O, does not have an
-associated transcoder and does not support textual I/O.  A @dfn{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.
-
address@hidden {Scheme Procedure} latin-1-codec
address@hidden {Scheme Procedure} utf-8-codec
address@hidden {Scheme Procedure} utf-16-codec
-
-These are predefined codecs for the ISO 8859-1, UTF-8, and UTF-16
-encoding schemes.
-
-A call to any of these procedures returns a value that is equal in the
-sense of @code{eqv?} to the result of any other call to the same
-procedure.
address@hidden deffn
-
address@hidden {Scheme Syntax} eol-style @var{eol-style-symbol}
-
address@hidden should be a symbol whose name is one of
address@hidden, @code{cr}, @code{crlf}, @code{nel}, @code{crnel}, @code{ls},
-and @code{none}.
-
-The form evaluates to the corresponding symbol.  If the name of
address@hidden 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 @var{eol-style} argument to
address@hidden  Otherwise, an exception is raised.
-
-All eol-style symbols except @code{none} describe a specific
-line-ending encoding:
-
address@hidden @code
address@hidden lf
-linefeed
address@hidden cr
-carriage return
address@hidden crlf
-carriage return, linefeed
address@hidden nel
-next line
address@hidden crnel
-carriage return, next line
address@hidden ls
-line separator
address@hidden table
-
-For a textual port with a transcoder, and whose transcoder has an
-eol-style symbol @code{none}, no conversion occurs.  For a textual input
-port, any eol-style symbol other than @code{none} means that all of the
-above line-ending encodings are recognized and are translated into a
-single linefeed.  For a textual output port, @code{none} and @code{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.
-
address@hidden Note
-  Only the name of @var{eol-style-symbol} is significant.
address@hidden quotation
address@hidden deffn
-
address@hidden {Scheme Procedure} native-eol-style
-Returns the default end-of-line style of the underlying platform, e.g.,
address@hidden on Unix and @code{crlf} on Windows.
address@hidden deffn
-
address@hidden {Condition Type} &i/o-decoding
address@hidden {Scheme Procedure} make-i/o-decoding-error  port
address@hidden {Scheme Procedure} i/o-decoding-error?  obj
-
-This condition type could be defined by
-
address@hidden
-(define-condition-type &i/o-decoding &i/o-port
-  make-i/o-decoding-error i/o-decoding-error?)
address@hidden lisp
-
-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.
address@hidden deffn
-
address@hidden {Condition Type} &i/o-encoding
address@hidden {Scheme Procedure} make-i/o-encoding-error  port char
address@hidden {Scheme Procedure} i/o-encoding-error?  obj
address@hidden {Scheme Procedure} i/o-encoding-error-char  condition
-
-This condition type could be defined by
-
address@hidden
-(define-condition-type &i/o-encoding &i/o-port
-  make-i/o-encoding-error i/o-encoding-error?
-  (char i/o-encoding-error-char))
address@hidden lisp
-
-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.
address@hidden is the character that could not be encoded.
address@hidden deffn
-
address@hidden {Scheme Syntax} error-handling-mode 
@var{error-handling-mode-symbol}
-
address@hidden should be a symbol whose name is one of
address@hidden, @code{raise}, and @code{replace}. The form evaluates to
-the corresponding symbol.  If @var{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 @var{handling-mode} argument to
address@hidden  If it is not acceptable as a
address@hidden argument to @code{make-transcoder}, an exception is
-raised.
-
address@hidden Note
-  Only the name of @var{error-handling-mode-symbol} is significant.
address@hidden quotation
-
-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 @code{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 @code{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 @code{raise}, an exception with condition
-type @code{&i/o-decoding} is raised.
-
-If a textual output operation encounters a character it cannot encode,
-and the error-handling mode is @code{ignore}, the character is ignored
-and encoding continues with the next character.  If the error-handling
-mode is @code{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 @code{?}  character
-for the Latin-1 encoding.  If the error-handling mode is @code{raise},
-an exception with condition type @code{&i/o-encoding} is raised.
address@hidden deffn
-
address@hidden {Scheme Procedure} make-transcoder  codec
address@hidden {Scheme Procedure} make-transcoder codec eol-style
address@hidden {Scheme Procedure} make-transcoder codec eol-style handling-mode
-
address@hidden must be a codec; @var{eol-style}, if present, an eol-style
-symbol; and @var{handling-mode}, if present, an error-handling-mode
-symbol.
-
address@hidden may be omitted, in which case it defaults to the native
-end-of-line style of the underlying platform.  @var{handling-mode} may
-be omitted, in which case it defaults to @code{replace}.  The result is
-a transcoder with the behavior specified by its arguments.
address@hidden deffn
-
address@hidden {Scheme procedure} native-transcoder
-Returns an implementation-dependent transcoder that represents a
-possibly locale-dependent ``native'' transcoding.
address@hidden deffn
-
address@hidden {Scheme Procedure} transcoder-codec  transcoder
address@hidden {Scheme Procedure} transcoder-eol-style  transcoder
address@hidden {Scheme Procedure} transcoder-error-handling-mode  transcoder
-
-These are accessors for transcoder objects; when applied to a
-transcoder returned by @code{make-transcoder}, they return the
address@hidden, @var{eol-style}, and @var{handling-mode} arguments,
-respectively.
address@hidden deffn
-
address@hidden {Scheme Procedure} bytevector->string  bytevector transcoder
-
-Returns the string that results from transcoding the
address@hidden according to the input direction of the transcoder.
address@hidden deffn
address@hidden Venerable Port Interfaces
address@hidden Venerable Port Interfaces
 
address@hidden {Scheme Procedure} string->bytevector  string transcoder
address@hidden char-ready?
address@hidden {Scheme Procedure} char-ready? [port]
address@hidden {C Function} scm_char_ready_p (port)
+Return @code{#t} if a character is ready on input @var{port}
+and return @code{#f} otherwise.  If @code{char-ready?} returns
address@hidden then the next @code{read-char} operation on
address@hidden is guaranteed not to hang.  If @var{port} is a file
+port at end of file then @code{char-ready?} returns @code{#t}.
 
-Returns the bytevector that results from transcoding the
address@hidden according to the output direction of the transcoder.
address@hidden 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 @code{char-ready?} cannot be rubbed out.
+If @code{char-ready?} were to return @code{#f} at end of file,
+a port at end of file would be indistinguishable from an
+interactive port that has no ready characters.
 @end deffn
 
address@hidden R6RS End-of-File
address@hidden The End-of-File Object
-
address@hidden EOF
address@hidden end-of-file
-
-R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io
-ports)} module:
-
address@hidden {Scheme Procedure} eof-object? obj
address@hidden {C Function} scm_eof_object_p (obj)
-Return true if @var{obj} is the end-of-file (EOF) object.
address@hidden read-char
address@hidden {Scheme Procedure} read-char [port]
address@hidden {C Function} scm_read_char (port)
+Return the next character available from @var{port}, updating @var{port}
+to point to the following character.  If no more characters are
+available, the end-of-file object is returned.  A decoding error, if
+any, is handled in accordance with the port's conversion strategy.
 @end deffn
 
-In addition, the following procedure is provided:
address@hidden peek-char
address@hidden {Scheme Procedure} peek-char [port]
address@hidden {C Function} scm_peek_char (port)
+Return the next character available from @var{port},
address@hidden updating @var{port} to point to the following
+character.  If no more characters are available, the
+end-of-file object is returned.
 
address@hidden {Scheme Procedure} eof-object
address@hidden {C Function} scm_eof_object ()
-Return the end-of-file (EOF) object.
+The value returned by
+a call to @code{peek-char} is the same as the value that would
+have been returned by a call to @code{read-char} on the same
+port.  The only difference is that the very next call to
address@hidden or @code{peek-char} on that @var{port} will
+return the value returned by the preceding call to
address@hidden  In particular, a call to @code{peek-char} on
+an interactive port will hang waiting for input whenever a call
+to @code{read-char} would have hung.
 
address@hidden
-(eof-object? (eof-object))
address@hidden #t
address@hidden lisp
+As for @code{read-char}, decoding errors are handled in accordance with
+the port's conversion strategy.
 @end deffn
 
-
address@hidden R6RS Port Manipulation
address@hidden Port Manipulation
-
-The procedures listed below operate on any kind of R6RS I/O port.
-
address@hidden {Scheme Procedure} port? obj
-Returns @code{#t} if the argument is a port, and returns @code{#f}
-otherwise.
address@hidden {Scheme Procedure} unread-char cobj [port]
address@hidden {C Function} scm_unread_char (cobj, port)
+Place character @var{cobj} in @var{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.  If @var{port} is
+not supplied, the current input port is used.
 @end deffn
 
address@hidden {Scheme Procedure} port-transcoder port
-Returns the transcoder associated with @var{port} if @var{port} is
-textual and has an associated transcoder, and returns @code{#f} if
address@hidden is binary or does not have an associated transcoder.
address@hidden {Scheme Procedure} unread-string str port
address@hidden {C Function} scm_unread_string (str, port)
+Place the string @var{str} in @var{port} so that its characters will
+be read from left-to-right as the next characters from @var{port}
+during subsequent read operations.  If called multiple times, the
+unread characters will be read again in last-in first-out order.  If
address@hidden is not supplied, the @code{current-input-port} is used.
 @end deffn
 
address@hidden {Scheme Procedure} binary-port? port
-Return @code{#t} if @var{port} is a @dfn{binary port}, suitable for
-binary data input/output.
-
-Note that internally Guile does not differentiate between binary and
-textual ports, unlike the R6RS.  Thus, this procedure returns true when
address@hidden does not have an associated encoding---i.e., when
address@hidden(port-encoding @var{port})} is @code{#f} (@pxref{Ports,
-port-encoding}).  This is the case for ports returned by R6RS procedures
-such as @code{open-bytevector-input-port} and
address@hidden
-
-However, Guile currently does not prevent use of textual I/O procedures
-such as @code{display} or @code{read-char} with binary ports.  Doing so
-``upgrades'' the port from binary to textual, under the ISO-8859-1
-encoding.  Likewise, Guile does not prevent use of
address@hidden on a binary port, which also turns it into a
-``textual'' port.
address@hidden newline
address@hidden {Scheme Procedure} newline [port]
address@hidden {C Function} scm_newline (port)
+Send a newline to @var{port}.
+If @var{port} is omitted, send to the current output port.
 @end deffn
 
address@hidden {Scheme Procedure} textual-port? port
-Always return @code{#t}, as all ports can be used for textual I/O in
-Guile.
address@hidden write-char
address@hidden {Scheme Procedure} write-char chr [port]
address@hidden {C Function} scm_write_char (chr, port)
+Send character @var{chr} to @var{port}.
 @end deffn
 
address@hidden {Scheme Procedure} transcoded-port binary-port transcoder
-The @code{transcoded-port} procedure
-returns a new textual port with the specified @var{transcoder}.
-Otherwise the new textual port's state is largely the same as
-that of @var{binary-port}.
-If @var{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
address@hidden
-If @var{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 @var{binary-port}.
address@hidden Using Ports from C
address@hidden Using Ports from C
 
-As a side effect, however, @code{transcoded-port}
-closes @var{binary-port} in
-a special way that allows the new textual port to continue to
-use the byte source or sink represented by @var{binary-port},
-even though @var{binary-port} itself is closed and cannot
-be used by the input and output operations described in this
-chapter.
address@hidden deffn
address@hidden {C Function} size_t scm_c_read (SCM port, void *buffer, size_t 
size)
+Read up to @var{size} bytes from @var{port} and store them in
address@hidden  The return value is the number of bytes actually read,
+which can be less than @var{size} if end-of-file has been reached.
 
address@hidden {Scheme Procedure} port-position port
-If @var{port} supports it (see below), return the offset (an integer)
-indicating where the next octet will be read from/written to in
address@hidden  If @var{port} does not support this operation, an error
-condition is raised.
+Note that this function does not update @code{port-line} and
address@hidden below.
address@hidden deftypefn
 
-This is similar to Guile's @code{seek} procedure with the
address@hidden argument (@pxref{Random Access}).
address@hidden deffn
address@hidden {C Function} void scm_c_write (SCM port, const void *buffer, 
size_t size)
+Write @var{size} bytes at @var{buffer} to @var{port}.
 
address@hidden {Scheme Procedure} port-has-port-position? port
-Return @code{#t} is @var{port} supports @code{port-position}.
address@hidden deffn
+Note that this function does not update @code{port-line} and
address@hidden (@pxref{Textual I/O}).
address@hidden deftypefn
 
address@hidden {Scheme Procedure} set-port-position! port offset
-If @var{port} supports it (see below), set the position where the next
-octet will be read from/written to @var{port} to @var{offset} (an
-integer).  If @var{port} does not support this operation, an error
-condition is raised.
-
-This is similar to Guile's @code{seek} procedure with the
address@hidden argument (@pxref{Random Access}).
address@hidden deffn
-
address@hidden {Scheme Procedure} port-has-set-port-position!? port
-Return @code{#t} is @var{port} supports @code{set-port-position!}.
address@hidden deffn
-
address@hidden {Scheme Procedure} call-with-port port proc
-Call @var{proc}, passing it @var{port} and closing @var{port} upon exit
-of @var{proc}.  Return the return values of @var{proc}.
address@hidden deffn
-
address@hidden R6RS Input Ports
address@hidden Input Ports
-
address@hidden {Scheme Procedure} input-port? obj
-Returns @code{#t} if the argument is an input port (or a combined input
-and output port), and returns @code{#f} otherwise.
address@hidden deffn
-
address@hidden {Scheme Procedure} port-eof? input-port
-Returns @code{#t}
-if the @code{lookahead-u8} procedure (if @var{input-port} is a binary port)
-or the @code{lookahead-char} procedure (if @var{input-port} is a textual port)
-would return
-the end-of-file object, and @code{#f} otherwise.
-The operation may block indefinitely if no data is available
-but the port cannot be determined to be at end of file.
address@hidden deffn
-
address@hidden {Scheme Procedure} open-file-input-port filename
address@hidden {Scheme Procedure} open-file-input-port filename file-options
address@hidden {Scheme Procedure} open-file-input-port filename file-options 
buffer-mode
address@hidden {Scheme Procedure} open-file-input-port filename file-options 
buffer-mode maybe-transcoder
address@hidden must be either a transcoder or @code{#f}.
-
-The @code{open-file-input-port} procedure returns an
-input port for the named file. The @var{file-options} and
address@hidden arguments are optional.
-
-The @var{file-options} argument, which may determine
-various aspects of the returned port (@pxref{R6RS File Options}),
-defaults to the value of @code{(file-options)}.
-
-The @var{buffer-mode} argument, if supplied,
-must be one of the symbols that name a buffer mode.
-The @var{buffer-mode} argument defaults to @code{block}.
-
-If @var{maybe-transcoder} is a transcoder, it becomes the transcoder associated
-with the returned port.
-
-If @var{maybe-transcoder} is @code{#f} or absent,
-the port will be a binary port and will support the
address@hidden and @code{set-port-position!}  operations.
-Otherwise the port will be a textual port, and whether it supports
-the @code{port-position} and @code{set-port-position!} operations
-is implementation-dependent (and possibly transcoder-dependent).
address@hidden deffn
-
address@hidden {Scheme Procedure} standard-input-port
-Returns a fresh binary input port connected to standard input.  Whether
-the port supports the @code{port-position} and @code{set-port-position!}
-operations is implementation-dependent.
address@hidden deffn
-
address@hidden {Scheme Procedure} current-input-port
-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 @code{with-input-from-file} procedure from the
address@hidden simple (6)} library (@pxref{rnrs io simple}).  The port may or
-may not have an associated transcoder; if it does, the transcoder is
-implementation-dependent.
address@hidden deffn
-
address@hidden R6RS Binary Input
address@hidden Binary Input
-
address@hidden binary input
-
-R6RS binary input ports can be created with the procedures described
-below.
-
address@hidden {Scheme Procedure} open-bytevector-input-port bv [transcoder]
address@hidden {C Function} scm_open_bytevector_input_port (bv, transcoder)
-Return an input port whose contents are drawn from bytevector @var{bv}
-(@pxref{Bytevectors}).
-
address@hidden FIXME: Update description when implemented.
-The @var{transcoder} argument is currently not supported.
address@hidden deffn
-
address@hidden custom binary input ports
-
address@hidden {Scheme Procedure} make-custom-binary-input-port id read! 
get-position set-position! close
address@hidden {C Function} scm_make_custom_binary_input_port (id, read!, 
get-position, set-position!, close)
-Return a new custom binary input address@hidden is similar in spirit
-to Guile's @dfn{soft ports} (@pxref{Soft Ports}).} named @var{id} (a
-string) whose input is drained by invoking @var{read!} and passing it a
-bytevector, an index where bytes should be written, and the number of
-bytes to read.  The @code{read!}  procedure must return an integer
-indicating the number of bytes read, or @code{0} to indicate the
-end-of-file.
-
-Optionally, if @var{get-position} is not @code{#f}, it must be a thunk
-that will be called when @code{port-position} is invoked on the custom
-binary port and should return an integer indicating the position within
-the underlying data stream; if @var{get-position} was not supplied, the
-returned port does not support @code{port-position}.
-
-Likewise, if @var{set-position!} is not @code{#f}, it should be a
-one-argument procedure.  When @code{set-port-position!} is invoked on the
-custom binary input port, @var{set-position!} is passed an integer
-indicating the position of the next byte is to read.
-
-Finally, if @var{close} is not @code{#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 @code{setvbuf} (@pxref{Buffering}).
-
-Using a custom binary input port, the @code{open-bytevector-input-port}
-procedure could be implemented as follows:
-
address@hidden
-(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!))
-
-(read (open-bytevector-input-port (string->utf8 "hello")))
address@hidden hello
address@hidden lisp
address@hidden deffn
-
address@hidden binary input
-Binary input is achieved using the procedures below:
-
address@hidden {Scheme Procedure} get-u8 port
address@hidden {C Function} scm_get_u8 (port)
-Return an octet read from @var{port}, a binary input port, blocking as
-necessary, or the end-of-file object.
address@hidden deffn
-
address@hidden {Scheme Procedure} lookahead-u8 port
address@hidden {C Function} scm_lookahead_u8 (port)
-Like @code{get-u8} but does not update @var{port}'s position to point
-past the octet.
address@hidden deffn
-
address@hidden {Scheme Procedure} get-bytevector-n port count
address@hidden {C Function} scm_get_bytevector_n (port, count)
-Read @var{count} octets from @var{port}, blocking as necessary and
-return a bytevector containing the octets read.  If fewer bytes are
-available, a bytevector smaller than @var{count} is returned.
address@hidden deffn
-
address@hidden {Scheme Procedure} get-bytevector-n! port bv start count
address@hidden {C Function} scm_get_bytevector_n_x (port, bv, start, count)
-Read @var{count} bytes from @var{port} and store them in @var{bv}
-starting at index @var{start}.  Return either the number of bytes
-actually read or the end-of-file object.
address@hidden deffn
-
address@hidden {Scheme Procedure} get-bytevector-some port
address@hidden {C Function} scm_get_bytevector_some (port)
-Read from @var{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.
address@hidden deffn
-
address@hidden {Scheme Procedure} get-bytevector-all port
address@hidden {C Function} scm_get_bytevector_all (port)
-Read from @var{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).
address@hidden deffn
-
-The @code{(ice-9 binary-ports)} module provides the following procedure
-as an extension to @code{(rnrs io ports)}:
-
address@hidden {Scheme Procedure} unget-bytevector port bv [start [count]]
address@hidden {C Function} scm_unget_bytevector (port, bv, start, count)
-Place the contents of @var{bv} in @var{port}, optionally starting at
-index @var{start} and limiting to @var{count} octets, so that its bytes
-will be read from left-to-right as the next bytes from @var{port} during
-subsequent read operations.  If called multiple times, the unread bytes
-will be read again in last-in first-out order.
address@hidden deffn
-
address@hidden R6RS Textual Input
address@hidden Textual Input
-
address@hidden {Scheme Procedure} get-char textual-input-port
-Reads from @var{textual-input-port}, blocking as necessary, until a
-complete character is available from @var{textual-input-port},
-or until an end of file is reached.
-
-If a complete character is available before the next end of file,
address@hidden 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, @code{get-char} returns the end-of-file object.
address@hidden deffn
-
address@hidden {Scheme Procedure} lookahead-char textual-input-port
-The @code{lookahead-char} procedure is like @code{get-char}, but it does
-not update @var{textual-input-port} to point past the character.
address@hidden deffn
-
address@hidden {Scheme Procedure} get-string-n textual-input-port count
-
address@hidden must be an exact, non-negative integer object, representing
-the number of characters to be read.
-
-The @code{get-string-n} procedure reads from @var{textual-input-port},
-blocking as necessary, until @var{count} characters are available, or
-until an end of file is reached.
-
-If @var{count} characters are available before end of file,
address@hidden returns a string consisting of those @var{count}
-characters. If fewer characters are available before an end of file, but
-one or more characters can be read, @code{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.
address@hidden deffn
-
address@hidden {Scheme Procedure} get-string-n! textual-input-port string start 
count
-
address@hidden and @var{count} must be exact, non-negative integer objects,
-with @var{count} representing the number of characters to be read.
address@hidden must be a string with at least address@hidden + @var{count}$
-characters.
-
-The @code{get-string-n!} procedure reads from @var{textual-input-port}
-in the same manner as @code{get-string-n}.  If @var{count} characters
-are available before an end of file, they are written into @var{string}
-starting at index @var{start}, and @var{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 @var{string} starting at index
address@hidden 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.
address@hidden deffn
-
address@hidden {Scheme Procedure} get-string-all textual-input-port
-Reads from @var{textual-input-port} until an end of file, decoding
-characters in the same manner as @code{get-string-n} and
address@hidden
-
-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.
address@hidden deffn
-
address@hidden {Scheme Procedure} get-line textual-input-port
-Reads from @var{textual-input-port} up to and including the linefeed
-character or end of file, decoding characters in the same manner as
address@hidden and @code{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.
-
address@hidden Note
-  The end-of-line style, if not @code{none}, will cause all line endings
-  to be read as linefeed characters.  @xref{R6RS Transcoders}.
address@hidden quotation
address@hidden deffn
-
address@hidden {Scheme Procedure} get-datum textual-input-port count
-Reads an external representation from @var{textual-input-port} and returns the
-datum it represents.  The @code{get-datum} procedure returns the next
-datum that can be parsed from the given @var{textual-input-port}, updating
address@hidden to point exactly past the end of the external
-representation of the object.
-
-Any @emph{interlexeme space} (comment or whitespace, @pxref{Scheme
-Syntax}) in the input is first skipped.  If an end of file occurs after
-the interlexeme space, the end-of-file object (@pxref{R6RS End-of-File})
-is returned.
-
-If a character inconsistent with an external representation is
-encountered in the input, an exception with condition types
address@hidden&lexical} and @code{&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 @code{&lexical} and
address@hidden&i/o-read} is raised.
address@hidden deffn
-
address@hidden R6RS Output Ports
address@hidden Output Ports
-
address@hidden {Scheme Procedure} output-port? obj
-Returns @code{#t} if the argument is an output port (or a
-combined input and output port), @code{#f} otherwise.
address@hidden deffn
-
address@hidden {Scheme Procedure} flush-output-port port
-Flushes any buffered output from the buffer of @var{output-port} to the
-underlying file, device, or object. The @code{flush-output-port}
-procedure returns an unspecified values.
address@hidden deffn
-
address@hidden {Scheme Procedure} open-file-output-port filename
address@hidden {Scheme Procedure} open-file-output-port filename file-options
address@hidden {Scheme Procedure} open-file-output-port filename file-options 
buffer-mode
address@hidden {Scheme Procedure} open-file-output-port filename file-options 
buffer-mode maybe-transcoder
-
address@hidden must be either a transcoder or @code{#f}.
-
-The @code{open-file-output-port} procedure returns an output port for the 
named file.
-
-The @var{file-options} argument, which may determine various aspects of
-the returned port (@pxref{R6RS File Options}), defaults to the value of
address@hidden(file-options)}.
-
-The @var{buffer-mode} argument, if supplied,
-must be one of the symbols that name a buffer mode.
-The @var{buffer-mode} argument defaults to @code{block}.
-
-If @var{maybe-transcoder} is a transcoder, it becomes the transcoder
-associated with the port.
-
-If @var{maybe-transcoder} is @code{#f} or absent,
-the port will be a binary port and will support the
address@hidden and @code{set-port-position!}  operations.
-Otherwise the port will be a textual port, and whether it supports
-the @code{port-position} and @code{set-port-position!} operations
-is implementation-dependent (and possibly transcoder-dependent).
address@hidden deffn
-
address@hidden {Scheme Procedure} standard-output-port
address@hidden {Scheme Procedure} standard-error-port
-Returns a fresh binary output port connected to the standard output or
-standard error respectively.  Whether the port supports the
address@hidden and @code{set-port-position!} operations is
-implementation-dependent.
address@hidden deffn
-
address@hidden {Scheme Procedure} current-output-port
address@hidden {Scheme Procedure} current-error-port
-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
address@hidden can be dynamically re-assigned using the
address@hidden procedure from the @code{io simple (6)}
-library (@pxref{rnrs io simple}).  A port returned by one of these
-procedures may or may not have an associated transcoder; if it does, the
-transcoder is implementation-dependent.
address@hidden deffn
-
address@hidden R6RS Binary Output
address@hidden Binary Output
-
-Binary output ports can be created with the procedures below.
-
address@hidden {Scheme Procedure} open-bytevector-output-port [transcoder]
address@hidden {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.
-
address@hidden
-(call-with-values
-  (lambda ()
-    (open-bytevector-output-port))
-  (lambda (port get-bytevector)
-    (display "hello" port)
-    (get-bytevector)))
-
address@hidden #vu8(104 101 108 108 111)
address@hidden lisp
-
address@hidden FIXME: Update description when implemented.
-The @var{transcoder} argument is currently not supported.
address@hidden deffn
-
address@hidden custom binary output ports
-
address@hidden {Scheme Procedure} make-custom-binary-output-port id write! 
get-position set-position! close
address@hidden {C Function} scm_make_custom_binary_output_port (id, write!, 
get-position, set-position!, close)
-Return a new custom binary output port named @var{id} (a string) whose
-output is sunk by invoking @var{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 @code{write!}  procedure must return an
-integer indicating the number of bytes actually written; when it is
-passed @code{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 @code{make-custom-binary-input-port}
-(@pxref{R6RS Binary Input, @code{make-custom-binary-input-port}}).
address@hidden deffn
-
address@hidden binary output
-Writing to a binary output port can be done using the following
-procedures:
-
address@hidden {Scheme Procedure} put-u8 port octet
address@hidden {C Function} scm_put_u8 (port, octet)
-Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
-binary output port.
address@hidden deffn
-
address@hidden {Scheme Procedure} put-bytevector port bv [start [count]]
address@hidden {C Function} scm_put_bytevector (port, bv, start, count)
-Write the contents of @var{bv} to @var{port}, optionally starting at
-index @var{start} and limiting to @var{count} octets.
address@hidden deffn
-
address@hidden R6RS Textual Output
address@hidden Textual Output
-
address@hidden {Scheme Procedure} put-char port char
-Writes @var{char} to the port. The @code{put-char} procedure returns
-an unspecified value.
address@hidden deffn
-
address@hidden {Scheme Procedure} put-string port string
address@hidden {Scheme Procedure} put-string port string start
address@hidden {Scheme Procedure} put-string port string start count
-
address@hidden and @var{count} must be non-negative exact integer objects.
address@hidden must have a length of at least @address@hidden +
address@hidden  @var{start} defaults to 0.  @var{count} defaults to
address@hidden@code{(string-length @var{string})} - @var{start}}$. The
address@hidden procedure writes the @var{count} characters of
address@hidden starting at index @var{start} to the port.  The
address@hidden procedure returns an unspecified value.
address@hidden deffn
-
address@hidden {Scheme Procedure} put-datum textual-output-port datum
address@hidden should be a datum value.  The @code{put-datum} procedure
-writes an external representation of @var{datum} to
address@hidden  The specific external representation is
-implementation-dependent.  However, whenever possible, an implementation
-should produce a representation for which @code{get-datum}, when reading
-the representation, will return an object equal (in the sense of
address@hidden) to @var{datum}.
-
address@hidden Note
-  Not all datums may allow producing an external representation for which
-  @code{get-datum} will produce an object that is equal to the
-  original.  Specifically, NaNs contained in @var{datum} may make
-  this impossible.
address@hidden quotation
-
address@hidden Note
-  The @code{put-datum} procedure merely writes the external
-  representation, but no trailing delimiter.  If @code{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 @code{get-datum}.
address@hidden quotation
address@hidden deffn
address@hidden {C Function} void scm_lfwrite (const char *buffer, size_t size, 
SCM port)
+Write @var{size} bytes at @var{buffer} to @var{port}.  The @code{lf}
+indicates that unlike @code{scm_c_write}, this function updates the
+port's @code{port-line} and @code{port-column}, and also flushes the
+port if the data contains a newline (@code{\n}) and the port is
+line-buffered.
address@hidden deftypefn
 
 @node I/O Extensions
 @subsection Implementing New Port Types in C
@@ -2371,7 +1813,7 @@ for a prototype of an asynchronous I/O and concurrency 
facility.
 
 
 @node BOM Handling
address@hidden Handling of Unicode byte order marks.
address@hidden Handling of Unicode Byte Order Marks
 @cindex BOM
 @cindex byte order mark
 
diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi
index b09ae89..152bf46 100644
--- a/doc/ref/api-options.texi
+++ b/doc/ref/api-options.texi
@@ -241,7 +241,7 @@ procedures (@pxref{Arrays}).
 
 @item char-ready?
 Indicates that the @code{char-ready?} function is available
-(@pxref{Reading}).
+(@pxref{Venerable Port Interfaces}).
 
 @item complex
 Indicates support for complex numbers.
diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi
index c1e65d7..c3978c8 100644
--- a/doc/ref/misc-modules.texi
+++ b/doc/ref/misc-modules.texi
@@ -47,7 +47,7 @@ follows,
 @table @asis
 @item @nicode{#:display?} @var{flag}
 If @var{flag} is true then print using @code{display}.  The default is
address@hidden which means use @code{write} style.  (@pxref{Writing})
address@hidden which means use @code{write} style.  @xref{Scheme Write}.
 
 @item @nicode{#:per-line-prefix} @var{string}
 Print the given @var{string} as a prefix on each line.  The default is
@@ -106,7 +106,7 @@ follows,
 @table @asis
 @item @nicode{#:display?} @var{flag}
 If @var{flag} is true then print using @code{display}.  The default is
address@hidden which means use @code{write} style.  (@pxref{Writing})
address@hidden which means use @code{write} style.  @pxref{Scheme Write}.
 
 @item @nicode{#:width} @var{columns}
 Print within the given @var{columns}.  The default is 79.
@@ -204,7 +204,7 @@ Object output.  Parameters: @var{minwidth}, @var{padinc},
 @var{minpad}, @var{padchar}.
 
 @nicode{~a} outputs an argument like @code{display}, @nicode{~s}
-outputs an argument like @code{write} (@pxref{Writing}).  
+outputs an argument like @code{write} (@pxref{Scheme Write}).
 
 @example
 (format #t "~a" "foo") @print{} foo
@@ -242,9 +242,9 @@ no minimum or multiple).
 Character.  Parameter: @var{charnum}.
 
 Output a character.  The default is to simply output, as per
address@hidden (@pxref{Writing}).  @nicode{~@@c} prints in
address@hidden style.  @nicode{~:c} prints control characters (ASCII 0
-to 31) in @nicode{^X} form.
address@hidden (@pxref{Venerable Port Interfaces}).  @nicode{~@@c}
+prints in @code{write} style.  @nicode{~:c} prints control characters
+(ASCII 0 to 31) in @nicode{^X} form.
 
 @example
 (format #t "~c" #\z)        @print{} z
@@ -760,8 +760,9 @@ already so.
 (format #f "a~3,5'*@@tx") @result{} "a****x"
 @end example
 
address@hidden is implemented using @code{port-column} (@pxref{Reading}),
-so it works even there has been other output before @code{format}.
address@hidden is implemented using @code{port-column} (@pxref{Textual
+I/O}), so it works even there has been other output before
address@hidden
 
 @item @nicode{~~}
 Tilde character.  Parameter: @var{n}.
@@ -815,7 +816,7 @@ Output a formfeed character, or @var{n} many if a parameter 
is given.
 Force output.  No parameters.
 
 At the end of output, call @code{force-output} to flush any buffers on
-the destination (@pxref{Writing}).  @nicode{~!} can occur anywhere in
+the destination (@pxref{Buffering}).  @nicode{~!} can occur anywhere in
 the format string, but the force is done at the end of output.
 
 When output is to a string (destination @code{#f}), @nicode{~!} does
@@ -1112,10 +1113,10 @@ originating format, or similar.
 @sp 1
 Guile contains a @code{format} procedure even when the module
 @code{(ice-9 format)} is not loaded.  The default @code{format} is
address@hidden (@pxref{Writing}), it doesn't support all escape
-sequences documented in this section, and will signal an error if you
-try to use one of them.  The reason for two versions is that the full
address@hidden is fairly large and requires some time to load.
address@hidden (@pxref{Simple Output}), it doesn't support all
+escape sequences documented in this section, and will signal an error if
+you try to use one of them.  The reason for two versions is that the
+full @code{format} is fairly large and requires some time to load.
 @code{simple-format} is often adequate too.
 
 
@@ -1661,10 +1662,10 @@ returned.
 @end deffn
 
 @deffn {Scheme Procedure} port->stream port readproc
-Return a stream which is the values obtained by reading from
address@hidden using @var{readproc}.  Each read call is
address@hidden(@var{readproc} @var{port})}, and it should return an EOF object
-(@pxref{Reading}) at the end of input.
+Return a stream which is the values obtained by reading from @var{port}
+using @var{readproc}.  Each read call is @code{(@var{readproc}
address@hidden)}, and it should return an EOF object (@pxref{Binary I/O}) at
+the end of input.
 
 For example a stream of characters from a file,
 
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
index 8a8ab38..edcff9d 100644
--- a/doc/ref/posix.texi
+++ b/doc/ref/posix.texi
@@ -303,7 +303,7 @@ a port.
 
 @deffn {Scheme Procedure} close fd_or_port
 @deffnx {C Function} scm_close (fd_or_port)
-Similar to @code{close-port} (@pxref{Closing, close-port}),
+Similar to @code{close-port} (@pxref{Ports, close-port}),
 but also works on file descriptors.  A side
 effect of closing a file descriptor is that any ports using that file
 descriptor are moved to a different file descriptor and have
@@ -2320,8 +2320,8 @@ terminate, and return the wait status code.  The status 
is as per
 it can reap a pipe's child process, causing an error from a subsequent
 @code{close-pipe}.
 
address@hidden (@pxref{Closing}) can close a pipe, but it doesn't
-reap the child process.
address@hidden (@pxref{Ports}) can close a pipe, but it doesn't reap
+the child process.
 
 The garbage collector will close a pipe no longer in use, and reap the
 child process with @code{waitpid}.  If the child hasn't yet terminated
diff --git a/doc/ref/r6rs.texi b/doc/ref/r6rs.texi
index e5ffb78..a12964e 100644
--- a/doc/ref/r6rs.texi
+++ b/doc/ref/r6rs.texi
@@ -97,9 +97,9 @@ The @code{(rnrs io ports)} module is incomplete.  Work is
 ongoing to fix this.
 
 @item
-Guile does not prevent use of textual I/O procedures on binary ports.
-More generally, it does not make a sharp distinction between binary and
-textual ports (@pxref{R6RS Port Manipulation, binary-port?}).
+Guile does not prevent use of textual I/O procedures on binary ports, or
+vice versa.  All ports in Guile support both binary and textual I/O.
address@hidden, for full details.
 
 @item
 Guile's implementation of @code{equal?} may fail to terminate when
@@ -147,8 +147,10 @@ Language Scheme}).
 * rnrs exceptions::             Handling exceptional situations.
 * rnrs conditions::             Data structures for exceptions.
 
-* I/O Conditions::              Predefined I/O error types.
+* R6RS I/O Conditions::         Predefined I/O error types.
+* R6RS Transcoders::            Characters and bytes.
 * rnrs io ports::               Support for port-based I/O.
+* R6RS File Ports::             Working with files.
 * rnrs io simple::              High-level I/O API.
 
 * rnrs files::                  Functions for working with files.
@@ -1343,7 +1345,7 @@ A subtype of @code{&violation} that indicates a reference 
to an unbound
 identifier.
 @end deffn
 
address@hidden I/O Conditions
address@hidden R6RS I/O Conditions
 @subsubsection I/O Conditions
 
 These condition types are exported by both the 
@@ -1420,21 +1422,547 @@ A subtype of @code{&i/o}; represents an error related 
to an operation on
 the port @var{port}.
 @end deffn
 
address@hidden R6RS Transcoders
address@hidden Transcoders
address@hidden codec
address@hidden end-of-line style
address@hidden transcoder
address@hidden binary port
address@hidden textual port
+
+The transcoder facilities are exported by @code{(rnrs io ports)}.
+
+Several different Unicode encoding schemes describe standard ways to
+encode characters and strings as byte sequences and to decode those
+sequences. Within this document, a @dfn{codec} is an immutable Scheme
+object that represents a Unicode or similar encoding scheme.
+
+An @dfn{end-of-line style} is a symbol that, if it is not @code{none},
+describes how a textual port transcodes representations of line endings.
+
+A @dfn{transcoder} is an immutable Scheme object that combines a codec
+with an end-of-line style and a method for handling decoding errors.
+Each transcoder represents some specific bidirectional (but not
+necessarily lossless), possibly stateful translation between byte
+sequences and Unicode characters and strings.  Every transcoder can
+operate in the input direction (bytes to characters) or in the output
+direction (characters to bytes).  A @var{transcoder} parameter name
+means that the corresponding argument must be a transcoder.
+
+A @dfn{binary port} is a port that supports binary I/O, does not have an
+associated transcoder and does not support textual I/O.  A @dfn{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.
+
address@hidden {Scheme Procedure} latin-1-codec
address@hidden {Scheme Procedure} utf-8-codec
address@hidden {Scheme Procedure} utf-16-codec
+
+These are predefined codecs for the ISO 8859-1, UTF-8, and UTF-16
+encoding schemes.
+
+A call to any of these procedures returns a value that is equal in the
+sense of @code{eqv?} to the result of any other call to the same
+procedure.
address@hidden deffn
+
address@hidden {Scheme Syntax} eol-style @var{eol-style-symbol}
+
address@hidden should be a symbol whose name is one of
address@hidden, @code{cr}, @code{crlf}, @code{nel}, @code{crnel}, @code{ls},
+and @code{none}.
+
+The form evaluates to the corresponding symbol.  If the name of
address@hidden 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 @var{eol-style} argument to
address@hidden  Otherwise, an exception is raised.
+
+All eol-style symbols except @code{none} describe a specific
+line-ending encoding:
+
address@hidden @code
address@hidden lf
+linefeed
address@hidden cr
+carriage return
address@hidden crlf
+carriage return, linefeed
address@hidden nel
+next line
address@hidden crnel
+carriage return, next line
address@hidden ls
+line separator
address@hidden table
+
+For a textual port with a transcoder, and whose transcoder has an
+eol-style symbol @code{none}, no conversion occurs.  For a textual input
+port, any eol-style symbol other than @code{none} means that all of the
+above line-ending encodings are recognized and are translated into a
+single linefeed.  For a textual output port, @code{none} and @code{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.
+
address@hidden Note
+  Only the name of @var{eol-style-symbol} is significant.
address@hidden quotation
address@hidden deffn
+
address@hidden {Scheme Procedure} native-eol-style
+Returns the default end-of-line style of the underlying platform, e.g.,
address@hidden on Unix and @code{crlf} on Windows.
address@hidden deffn
+
address@hidden {Condition Type} &i/o-decoding
address@hidden {Scheme Procedure} make-i/o-decoding-error  port
address@hidden {Scheme Procedure} i/o-decoding-error?  obj
+This condition type could be defined by
+
address@hidden
+(define-condition-type &i/o-decoding &i/o-port
+  make-i/o-decoding-error i/o-decoding-error?)
address@hidden lisp
+
+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.
address@hidden deffn
+
address@hidden {Condition Type} &i/o-encoding
address@hidden {Scheme Procedure} make-i/o-encoding-error  port char
address@hidden {Scheme Procedure} i/o-encoding-error?  obj
address@hidden {Scheme Procedure} i/o-encoding-error-char  condition
+This condition type could be defined by
+
address@hidden
+(define-condition-type &i/o-encoding &i/o-port
+  make-i/o-encoding-error i/o-encoding-error?
+  (char i/o-encoding-error-char))
address@hidden lisp
+
+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.
address@hidden is the character that could not be encoded.
address@hidden deffn
+
address@hidden {Scheme Syntax} error-handling-mode 
@var{error-handling-mode-symbol}
address@hidden should be a symbol whose name is one of
address@hidden, @code{raise}, and @code{replace}. The form evaluates to
+the corresponding symbol.  If @var{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 @var{handling-mode} argument to
address@hidden  If it is not acceptable as a
address@hidden argument to @code{make-transcoder}, an exception is
+raised.
+
address@hidden Note
+  Only the name of @var{error-handling-mode-symbol} is significant.
address@hidden quotation
+
+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 @code{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 @code{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 @code{raise}, an exception with condition
+type @code{&i/o-decoding} is raised.
+
+If a textual output operation encounters a character it cannot encode,
+and the error-handling mode is @code{ignore}, the character is ignored
+and encoding continues with the next character.  If the error-handling
+mode is @code{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 @code{?}  character
+for the Latin-1 encoding.  If the error-handling mode is @code{raise},
+an exception with condition type @code{&i/o-encoding} is raised.
address@hidden deffn
+
address@hidden {Scheme Procedure} make-transcoder  codec
address@hidden {Scheme Procedure} make-transcoder codec eol-style
address@hidden {Scheme Procedure} make-transcoder codec eol-style handling-mode
address@hidden must be a codec; @var{eol-style}, if present, an eol-style
+symbol; and @var{handling-mode}, if present, an error-handling-mode
+symbol.
+
address@hidden may be omitted, in which case it defaults to the native
+end-of-line style of the underlying platform.  @var{handling-mode} may
+be omitted, in which case it defaults to @code{replace}.  The result is
+a transcoder with the behavior specified by its arguments.
address@hidden deffn
+
address@hidden {Scheme procedure} native-transcoder
+Returns an implementation-dependent transcoder that represents a
+possibly locale-dependent ``native'' transcoding.
address@hidden deffn
+
address@hidden {Scheme Procedure} transcoder-codec  transcoder
address@hidden {Scheme Procedure} transcoder-eol-style  transcoder
address@hidden {Scheme Procedure} transcoder-error-handling-mode  transcoder
+These are accessors for transcoder objects; when applied to a
+transcoder returned by @code{make-transcoder}, they return the
address@hidden, @var{eol-style}, and @var{handling-mode} arguments,
+respectively.
address@hidden deffn
+
address@hidden {Scheme Procedure} bytevector->string  bytevector transcoder
+Returns the string that results from transcoding the
address@hidden according to the input direction of the transcoder.
address@hidden deffn
+
address@hidden {Scheme Procedure} string->bytevector  string transcoder
+Returns the bytevector that results from transcoding the
address@hidden according to the output direction of the transcoder.
address@hidden deffn
+
 @node rnrs io ports
 @subsubsection rnrs io ports
 
-The @code{(rnrs io ports (6))} library provides various procedures and
-syntactic forms for use in writing to and reading from ports.  This 
-functionality is documented in its own section of the manual;
-(@pxref{R6RS I/O Ports}).
address@hidden R6RS
address@hidden R6RS ports
+Guile's binary and textual port interface was heavily inspired by R6RS,
+so many R6RS port interfaces are documented elsewhere.  Note that R6RS
+ports are not disjoint from Guile's native ports, so Guile-specific
+procedures will work on ports created using the R6RS API, and vice
+versa.  Also note that in Guile, all ports are both textual and binary.
address@hidden and Output}, for more on Guile's core port API.  The R6RS
+ports module wraps Guile's I/O routines in a helper that will translate
+native Guile exceptions to R6RS conditions; @xref{R6RS I/O Conditions},
+for more.  @xref{R6RS File Ports}, for documentation on the R6RS file
+port interface.
+
address@hidden FIXME: Update description when implemented.
address@hidden: The implementation of this R6RS API is not complete yet.
+
address@hidden {Scheme Procedure} eof-object? obj
address@hidden I/O}, for documentation.
address@hidden deffn
+
address@hidden {Scheme Procedure} eof-object
+Return the end-of-file (EOF) object.
+
address@hidden
+(eof-object? (eof-object))
address@hidden #t
address@hidden lisp
address@hidden deffn
+
address@hidden {Scheme Procedure} port? obj
address@hidden {Scheme Procedure} input-port? obj
address@hidden {Scheme Procedure} output-port? obj
address@hidden, for documentation.
address@hidden deffn
+
address@hidden {Scheme Procedure} port-transcoder port
+Return a transcoder associated with the encoding of @var{port}.
address@hidden, and @xref{R6RS Transcoders}.
address@hidden deffn
+
address@hidden {Scheme Procedure} binary-port? port
address@hidden {Scheme Procedure} textual-port? port
+Return @code{#t}, as all ports in Guile are suitable for binary and
+textual I/O.  @xref{Encoding}, for more details.
address@hidden deffn
+
address@hidden {Scheme Procedure} transcoded-port binary-port transcoder
+The @code{transcoded-port} procedure
+returns a new textual port with the specified @var{transcoder}.
+Otherwise the new textual port's state is largely the same as
+that of @var{binary-port}.
+If @var{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
address@hidden
+If @var{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 @var{binary-port}.
+
+As a side effect, however, @code{transcoded-port}
+closes @var{binary-port} in
+a special way that allows the new textual port to continue to
+use the byte source or sink represented by @var{binary-port},
+even though @var{binary-port} itself is closed and cannot
+be used by the input and output operations described in this
+chapter.
address@hidden deffn
+
address@hidden {Scheme Procedure} port-position port
+Equivalent to @code{(seek @var{port} SEEK_CUR 0)}.  @xref{Random
+Access}.
address@hidden deffn
+
address@hidden {Scheme Procedure} port-has-port-position? port
+Return @code{#t} is @var{port} supports @code{port-position}.
address@hidden deffn
+
address@hidden {Scheme Procedure} set-port-position! port offset
+Equivalent to @code{(seek @var{port} SEEK_SET @var{offset})}.
address@hidden Access}.
address@hidden deffn
+
address@hidden {Scheme Procedure} port-has-set-port-position!? port
+Return @code{#t} is @var{port} supports @code{set-port-position!}.
address@hidden deffn
+
address@hidden {Scheme Procedure} call-with-port port proc
+Call @var{proc}, passing it @var{port} and closing @var{port} upon exit
+of @var{proc}.  Return the return values of @var{proc}.
address@hidden deffn
+
address@hidden {Scheme Procedure} port-eof? input-port
+Equivalent to @code{(eof-object? (lookahead-u8 @var{input-port}))}.
address@hidden deffn
+
address@hidden {Scheme Procedure} standard-input-port
address@hidden {Scheme Procedure} standard-output-port
address@hidden {Scheme Procedure} standard-error-port
+Returns a fresh binary input port connected to standard input, or a
+binary output port connected to the standard output or standard error,
+respectively.  Whether the port supports the @code{port-position} and
address@hidden  operations is implementation-dependent.
address@hidden deffn
+
address@hidden {Scheme Procedure} current-input-port
address@hidden {Scheme Procedure} current-output-port
address@hidden {Scheme Procedure} current-error-port
address@hidden Ports}.
address@hidden deffn
+
address@hidden {Scheme Procedure} open-bytevector-input-port bv [transcoder]
address@hidden {Scheme Procedure} open-bytevector-output-port [transcoder]
address@hidden Ports}.
address@hidden deffn
+
address@hidden {Scheme Procedure} make-custom-binary-input-port id read! 
get-position set-position! close
address@hidden {Scheme Procedure} make-custom-binary-output-port id write! 
get-position set-position! close
address@hidden Ports}.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-u8 port
address@hidden {Scheme Procedure} lookahead-u8 port
address@hidden {Scheme Procedure} get-bytevector-n port count
address@hidden {Scheme Procedure} get-bytevector-n! port bv start count
address@hidden {Scheme Procedure} get-bytevector-some port
address@hidden {Scheme Procedure} get-bytevector-all port
address@hidden {Scheme Procedure} put-u8 port octet
address@hidden {Scheme Procedure} put-bytevector port bv [start [count]]
address@hidden I/O}.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-char textual-input-port
address@hidden {Scheme Procedure} lookahead-char textual-input-port
address@hidden {Scheme Procedure} get-string-n textual-input-port count
address@hidden {Scheme Procedure} get-string-n! textual-input-port string start 
count
address@hidden {Scheme Procedure} get-string-all textual-input-port
address@hidden {Scheme Procedure} get-line textual-input-port
address@hidden {Scheme Procedure} put-char port char
address@hidden {Scheme Procedure} put-string port string [start [count]]
address@hidden I/O}.
address@hidden deffn
+
address@hidden {Scheme Procedure} get-datum textual-input-port count
+Reads an external representation from @var{textual-input-port} and returns the
+datum it represents.  The @code{get-datum} procedure returns the next
+datum that can be parsed from the given @var{textual-input-port}, updating
address@hidden to point exactly past the end of the external
+representation of the object.
+
+Any @emph{interlexeme space} (comment or whitespace, @pxref{Scheme
+Syntax}) in the input is first skipped.  If an end of file occurs after
+the interlexeme space, the end-of-file object is returned.
+
+If a character inconsistent with an external representation is
+encountered in the input, an exception with condition types
address@hidden&lexical} and @code{&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 @code{&lexical} and
address@hidden&i/o-read} is raised.
address@hidden deffn
+
address@hidden {Scheme Procedure} put-datum textual-output-port datum
address@hidden should be a datum value.  The @code{put-datum} procedure
+writes an external representation of @var{datum} to
address@hidden  The specific external representation is
+implementation-dependent.  However, whenever possible, an implementation
+should produce a representation for which @code{get-datum}, when reading
+the representation, will return an object equal (in the sense of
address@hidden) to @var{datum}.
+
address@hidden Note
+  Not all datums may allow producing an external representation for which
+  @code{get-datum} will produce an object that is equal to the
+  original.  Specifically, NaNs contained in @var{datum} may make
+  this impossible.
address@hidden quotation
+
address@hidden Note
+  The @code{put-datum} procedure merely writes the external
+  representation, but no trailing delimiter.  If @code{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 @code{get-datum}.
address@hidden quotation
address@hidden deffn
+
address@hidden {Scheme Procedure} flush-output-port port
address@hidden, for documentation on @code{force-output}.
address@hidden deffn
+
address@hidden R6RS File Ports
address@hidden R6RS File Ports
+
+The facilities described in this section are exported by the @code{(rnrs
+io ports)} module.
+
address@hidden {Scheme Syntax} buffer-mode @var{buffer-mode-symbol}
address@hidden must be a symbol whose name is one of
address@hidden, @code{line}, and @code{block}. The result is the
+corresponding symbol, and specifies the associated buffer mode.
address@hidden, for a discussion of these different buffer modes.  To
+control the amount of buffering, use @code{setvbuf} instead.  Note that
+only the name of @var{buffer-mode-symbol} is significant.
+
address@hidden, for a discussion of port buffering.
address@hidden deffn
+
address@hidden {Scheme Procedure} buffer-mode? obj
+Returns @code{#t} if the argument is a valid buffer-mode symbol, and
+returns @code{#f} otherwise.
address@hidden deffn
+
+When opening a file, the various procedures accept a @code{file-options}
+object that encapsulates flags to specify how the file is to be
+opened. A @code{file-options} object is an enum-set (@pxref{rnrs enums})
+over the symbols constituting valid file options.
+
+A @var{file-options} parameter name means that the corresponding
+argument must be a file-options object.
+
address@hidden {Scheme Syntax} file-options @var{file-options-symbol} ...
+
+Each @var{file-options-symbol} must be a symbol.
+
+The @code{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 @code{(file-options)} specifies that the
+file is created if it does not exist and an exception with condition
+type @code{&i/o-file-already-exists} is raised if it does exist.  The
+following standard options can be included to modify the default
+behavior.
+
address@hidden @code
address@hidden no-create
+      If the file does not already exist, it is not created;
+      instead, an exception with condition type @code{&i/o-file-does-not-exist}
+      is raised.
+      If the file already exists, the exception with condition type
+      @code{&i/o-file-already-exists} is not raised
+      and the file is truncated to zero length.
address@hidden no-fail
+      If the file already exists, the exception with condition type
+      @code{&i/o-file-already-exists} is not raised,
+      even if @code{no-create} is not included,
+      and the file is truncated to zero length.
address@hidden no-truncate
+      If the file already exists and the exception with condition type
+      @code{&i/o-file-already-exists} has been inhibited by inclusion of
+      @code{no-create} or @code{no-fail}, the file is not truncated, but
+      the port's current position is still set to the beginning of the
+      file.
address@hidden table
+
+These options have no effect when a file is opened only for input.
+Symbols other than those listed above may be used as
address@hidden; they have implementation-specific meaning,
+if any.
+
address@hidden Note
+  Only the name of @var{file-options-symbol} is significant.
address@hidden quotation
address@hidden deffn
+
address@hidden {Scheme Procedure} open-file-input-port filename
address@hidden {Scheme Procedure} open-file-input-port filename file-options
address@hidden {Scheme Procedure} open-file-input-port filename file-options 
buffer-mode
address@hidden {Scheme Procedure} open-file-input-port filename file-options 
buffer-mode maybe-transcoder
address@hidden must be either a transcoder or @code{#f}.
+
+The @code{open-file-input-port} procedure returns an
+input port for the named file. The @var{file-options} and
address@hidden arguments are optional.
+
+The @var{file-options} argument, which may determine various aspects of
+the returned port, defaults to the value of @code{(file-options)}.
+
+The @var{buffer-mode} argument, if supplied,
+must be one of the symbols that name a buffer mode.
+The @var{buffer-mode} argument defaults to @code{block}.
+
+If @var{maybe-transcoder} is a transcoder, it becomes the transcoder associated
+with the returned port.
+
+If @var{maybe-transcoder} is @code{#f} or absent,
+the port will be a binary port and will support the
address@hidden and @code{set-port-position!}  operations.
+Otherwise the port will be a textual port, and whether it supports
+the @code{port-position} and @code{set-port-position!} operations
+is implementation-dependent (and possibly transcoder-dependent).
address@hidden deffn
+
address@hidden {Scheme Procedure} open-file-output-port filename
address@hidden {Scheme Procedure} open-file-output-port filename file-options
address@hidden {Scheme Procedure} open-file-output-port filename file-options 
buffer-mode
address@hidden {Scheme Procedure} open-file-output-port filename file-options 
buffer-mode maybe-transcoder
address@hidden must be either a transcoder or @code{#f}.
+
+The @code{open-file-output-port} procedure returns an output port for the 
named file.
+
+The @var{file-options} argument, which may determine various aspects of
+the returned port, defaults to the value of @code{(file-options)}.
+
+The @var{buffer-mode} argument, if supplied,
+must be one of the symbols that name a buffer mode.
+The @var{buffer-mode} argument defaults to @code{block}.
+
+If @var{maybe-transcoder} is a transcoder, it becomes the transcoder
+associated with the port.
+
+If @var{maybe-transcoder} is @code{#f} or absent,
+the port will be a binary port and will support the
address@hidden and @code{set-port-position!}  operations.
+Otherwise the port will be a textual port, and whether it supports
+the @code{port-position} and @code{set-port-position!} operations
+is implementation-dependent (and possibly transcoder-dependent).
address@hidden deffn
 
 @node rnrs io simple
 @subsubsection rnrs io simple
 
 The @code{(rnrs io simple (6))} library provides convenience functions
 for performing textual I/O on ports.  This library also exports all of
-the condition types and associated procedures described in (@pxref{I/O
-Conditions}).  In the context of this section, when stating that a
+the condition types and associated procedures described in (@pxref{R6RS
+I/O Conditions}).  In the context of this section, when stating that a
 procedure behaves ``identically'' to the corresponding procedure in
 Guile's core library, this is modulo the behavior wrt. conditions: such
 procedures raise the appropriate R6RS conditions in case of error, but
@@ -1451,9 +1979,8 @@ appropriate R6RS conditions.
 
 @deffn {Scheme Procedure} eof-object
 @deffnx {Scheme Procedure} eof-object? obj
-These procedures are identical to the ones provided by the
address@hidden(rnrs io ports (6))} library.  @xref{R6RS I/O Ports}, for
-documentation.
+These procedures are identical to the ones provided by the @code{(rnrs
+io ports (6))} library.  @xref{rnrs io ports}, for documentation.
 @end deffn
 
 @deffn {Scheme Procedure} input-port? obj
@@ -1474,8 +2001,8 @@ library.  @xref{File Ports}, for documentation.
 
 @deffn {Scheme Procedure} close-input-port input-port
 @deffnx {Scheme Procedure} close-output-port output-port
-These procedures are identical to the ones provided by Guile's core
-library.  @xref{Closing}, for documentation.
+Closes the given @var{input-port} or @var{output-port}.  These are
+legacy interfaces; just use @code{close-port}.
 @end deffn
 
 @deffn {Scheme Procedure} peek-char
@@ -1483,7 +2010,7 @@ library.  @xref{Closing}, for documentation.
 @deffnx {Scheme Procedure} read-char
 @deffnx {Scheme Procedure} read-char textual-input-port
 These procedures are identical to the ones provided by Guile's core
-library.  @xref{Reading}, for documentation.
+library.  @xref{Venerable Port Interfaces}, for documentation.
 @end deffn
 
 @deffn {Scheme Procedure} read
@@ -1500,8 +2027,9 @@ This procedure is identical to the one provided by 
Guile's core library.
 @deffnx {Scheme Procedure} write obj textual-output-port
 @deffnx {Scheme Procedure} write-char char
 @deffnx {Scheme Procedure} write-char char textual-output-port
-These procedures are identical to the ones provided by Guile's core 
-library.  @xref{Writing}, for documentation.
+These procedures are identical to the ones provided by Guile's core
+library.  @xref{Venerable Port Interfaces}, and @xref{Scheme Write}, for
+documentation.
 @end deffn
 
 @node rnrs files
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index c890d7d..463592e 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -3302,8 +3302,8 @@ Insert a newline.
 Insert a tilde.
 @end table
 
-This procedure is the same as calling @code{simple-format} (@pxref{Writing})
-with @code{#f} as the destination.
+This procedure is the same as calling @code{simple-format}
+(@pxref{Simple Output}) with @code{#f} as the destination.
 @end deffn
 
 @node SRFI-30