mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-20 11:40:18 +02:00
Code Activity

reword open-file docs

Browse source 
* doc/ref/api-io.texi (File Ports): Refactor open-file docs.  Thanks to
  Bake Timmons for the report.
This commit is contained in:
Andy Wingo 2011-08-18 11:13:34 +02:00
parent 81bda963e9
commit 5261e74281
1 changed files with 19 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

38
doc/ref/api-io.texi
View file

@ -838,34 +838,34 @@ setvbuf}
Add line-buffering to the port. The port output buffer will be Add line-buffering to the port. The port output buffer will be
automatically flushed whenever a newline character is written. automatically flushed whenever a newline character is written.
@item b @item b
Use binary mode. On DOS systems the default text mode converts CR+LF Use binary mode, ensuring that each byte in the file will be read as one
in the file to newline for the program, whereas binary mode reads and Scheme character.
writes all bytes unchanged. On Unix-like systems there is no such
distinction, text files already contain just newlines and no
conversion is ever made. The @code{b} flag is accepted on all
systems, but has no effect on Unix-like systems.
(For reference, Guile leaves text versus binary up to the C library, To provide this property, the file will be opened with the 8-bit
@code{b} here just adds @code{O_BINARY} to the underlying @code{open} character encoding "ISO-8859-1", ignoring any coding declaration or port
call, when that flag is available.) encoding. @xref{Ports}, for more information on port encodings.
Also, open the file using the 8-bit character encoding "ISO-8859-1", Note that while it is possible to read and write binary data as
ignoring any coding declaration or port encoding. characters or strings, it is usually better to treat bytes as octets,
and byte sequences as bytevectors. @xref{R6RS Binary Input}, and
@ref{R6RS Binary Output}, for more.
Note that, when reading or writing binary data with ports, the This option had another historical meaning, for DOS compatibility: in
bytevector ports in the @code{(rnrs io ports)} module are preferred, the default (textual) mode, DOS reads a CR-LF sequence as one LF byte.
as they return vectors, and not strings (@pxref{R6RS I/O Ports}). The @code{b} flag prevents this from happening, adding @code{O_BINARY}
to the underlying @code{open} call. Still, the flag is generally useful
because of its port encoding ramifications.
@end table @end table
If a file cannot be opened with the access If a file cannot be opened with the access
requested, @code{open-file} throws an exception. requested, @code{open-file} throws an exception.
When the file is opened, this procedure will scan for a coding When the file is opened, this procedure will scan for a coding
declaration (@pxref{Character Encoding of Source Files}). If present declaration (@pxref{Character Encoding of Source Files}). If a coding
will use that encoding for interpreting the file. Otherwise, the declaration is found, it will be used to interpret the file. Otherwise,
port's encoding will be used. To suppress this behavior, open the port's encoding will be used. To suppress this behavior, open the
the file in binary mode and then set the port encoding explicitly file in binary mode and then set the port encoding explicitly using
using @code{set-port-encoding!}. @code{set-port-encoding!}.
In theory we could create read/write ports which were buffered In theory we could create read/write ports which were buffered
in one direction only. However this isn't included in the in one direction only. However this isn't included in the