@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009, 2010
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@page
@node Input and Output
@section Input and Output
* Block Reading and Writing:: Reading and writing blocks of 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.
* I/O Extensions:: Using and extending ports in C.
@end menu
@node Ports
@subsection Ports
+@cindex Port
Sequential input/output in Scheme is represented by operations on a
@dfn{port}. This chapter explains the operations that Guile provides
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 occuring in the close will not be reported.
+In this case any errors occurring in the close will not be reported.
Usually a program will want to explicitly close so as to be sure all
its operations have been successful. Of course if a program has
abandoned something due to an error or other condition then closing
If program flow makes it hard to be certain when to close then this
may be an acceptable way to control resource usage.
+All file access uses the ``LFS'' large file support functions when
+available, so files bigger than 2 Gbytes (@math{2^31} bytes) can be
+read and written on a 32-bit system.
+
+Each port has an associated character encoding that controls how bytes
+read from the port are converted to characters and string and controls
+how characters and strings written to the port are converted to bytes.
+When ports are created, they inherit their character encoding from the
+current locale, but, that can be modified after the port is created.
+
+Currently, the ports only work with @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.
+
+Each port also has an associated conversion strategy: what to do when
+a Guile character can't be converted to the port's encoded character
+representation for output. There are three possible strategies: to
+raise an error, to replace the character with a hex escape, or to
+replace the character with a substitute character.
+
@rnindex input-port?
@deffn {Scheme Procedure} input-port? x
@deffnx {C Function} scm_input_port_p (x)
@var{x}))}.
@end deffn
+@deffn {Scheme Procedure} set-port-encoding! port enc
+@deffnx {C Function} scm_set_port_encoding_x (port, enc)
+Sets the character encoding that will be used to interpret all port I/O.
+@var{enc} is a string containing the name of an encoding. Valid
+encoding names are those
+@url{http://www.iana.org/assignments/character-sets, defined by IANA}.
+@end deffn
+
+@defvr {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.
+@end defvr
+
+@deffn {Scheme Procedure} port-encoding port
+@deffnx {C Function} scm_port_encoding
+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"}.
+@end deffn
+
+@deffn {Scheme Procedure} set-port-conversion-strategy! port sym
+@deffnx {C Function} scm_set_port_conversion_strategy_x (port, sym)
+Sets the behavior of the interpreter when outputting a character that
+is not representable in the port's current encoding. @var{sym} can be
+either @code{'error}, @code{'substitute}, or @code{'escape}. If it is
+@code{'error}, an error will be thrown when an nonconvertible character
+is encountered. If it is @code{'substitute}, then nonconvertible
+characters will be replaced with approximate characters, or with
+question marks if no approximately correct character is available. If
+it is @code{'escape}, it will appear as a hex escape when output.
+
+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.
+@end deffn
+
+@deffn {Scheme Procedure} port-conversion-strategy port
+@deffnx {C Function} scm_port_conversion_strategy (port)
+Returns the behavior of the port when outputting a character that is
+not representable in the port's current encoding. It returns the
+symbol @code{error} if unrepresentable characters should cause
+exceptions, @code{substitute} if the port should try to replace
+unrepresentable characters with question marks or approximate
+characters, or @code{escape} if unrepresentable characters should be
+converted to string escapes.
+
+If @var{port} is @code{#f}, then the current default behavior will be
+returned. New ports will have this default behavior when they are
+created.
+@end deffn
+
+
@node Reading
@subsection Reading
+@cindex Reading
[Generic procedures for reading from ports.]
@rnindex eof-object?
+@cindex End of file object
@deffn {Scheme Procedure} eof-object? x
@deffnx {C Function} scm_eof_object_p (x)
Return @code{#t} if @var{x} is an end-of-file object; otherwise
@code{#t} then the next @code{read-char} operation on
@var{port} is guaranteed not to hang. If @var{port} is a file
port at end of file then @code{char-ready?} returns @code{#t}.
-@footnote{@code{char-ready?} exists to make it possible for a
+
+@code{char-ready?} exists to make it possible for a
program to accept characters from interactive ports without
getting stuck waiting for input. Any input editors associated
with such ports must make sure that characters whose existence
has been asserted by @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.}
+interactive port that has no ready characters.
@end deffn
@rnindex read-char
Return the next character available from @var{port},
@emph{without} updating @var{port} to point to the following
character. If no more characters are available, the
-end-of-file object is returned.@footnote{The value returned by
+end-of-file object is returned.
+
+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
return the value returned by the preceding call to
@code{peek-char}. 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.}
+to @code{read-char} would have hung.
@end deffn
@deffn {Scheme Procedure} unread-char cobj [port]
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
-@var{port} is not supplied, the current-input-port is used.
+@var{port} is not supplied, the @code{current-input-port} is used.
@end deffn
@deffn {Scheme Procedure} drain-input port
@node Writing
@subsection Writing
+@cindex Writing
[Generic procedures for writing to ports.]
The output is designed to be machine readable, and can be read back
with @code{read} (@pxref{Reading}). Strings are printed in
-doublequotes, with escapes if necessary, and characters are printed in
+double quotes, with escapes if necessary, and characters are printed in
@samp{#\} notation.
@end deffn
output port if not given.
The output is designed for human readability, it differs from
-@code{write} in that strings are printed without doublequotes and
+@code{write} in that strings are printed without double quotes and
escapes, and characters are printed as per @code{write-char}, not in
@samp{#\} form.
@end deffn
If @var{port} is omitted, send to the current output port.
@end deffn
-@deffn {Scheme Procedure} port-with-print-state port pstate
+@deffn {Scheme Procedure} port-with-print-state port [pstate]
@deffnx {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}.
+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.
@end deffn
@deffn {Scheme Procedure} print-options-interface [setting]
@node Closing
@subsection Closing
+@cindex Closing ports
+@cindex Port, close
@deffn {Scheme Procedure} close-port port
@deffnx {C Function} scm_close_port (port)
@node Random Access
@subsection Random Access
+@cindex Random access, ports
+@cindex Port, random access
@deffn {Scheme Procedure} seek fd_port offset whence
@deffnx {C Function} scm_seek (fd_port, offset, whence)
@findex truncate
@findex ftruncate
-@deffn {Scheme Procedure} truncate-file object [length]
-@deffnx {C Function} scm_truncate_file (object, length)
-Truncates the object referred to by @var{object} to at most
-@var{length} bytes. @var{object} can be a string containing a
-file name or an integer file descriptor or a port.
-@var{length} may be omitted if @var{object} is not a file name,
-in which case the truncation occurs at the current port.
-position. The return value is unspecified.
+@deffn {Scheme Procedure} truncate-file file [length]
+@deffnx {C Function} scm_truncate_file (file, length)
+Truncate @var{file} to @var{length} bytes. @var{file} can be a
+filename string, a port object, or an integer file descriptor. The
+return value is unspecified.
+
+For a port or file descriptor @var{length} can be omitted, in which
+case the file is truncated at the current position (per @code{ftell}
+above).
+
+On most systems a file can be extended by giving a length greater than
+the current size, but this is not mandatory in the POSIX standard.
@end deffn
@node Line/Delimited
@subsection Line Oriented and Delimited Text
+@cindex Line input/output
+@cindex Port, line input/output
The delimited-I/O module can be accessed with:
-@smalllisp
+@lisp
(use-modules (ice-9 rdelim))
-@end smalllisp
+@end lisp
It can be used to read or write lines of text, or read text delimited by
a specified set of characters. It's similar to the @code{(scsh rdelim)}
@end lisp
@end deffn
-Some of the abovementioned I/O functions rely on the following C
+Some of the aforementioned I/O functions rely on the following C
primitives. These will mainly be of interest to people hacking Guile
internals.
@node Block Reading and Writing
@subsection Block reading and writing
+@cindex Block read/write
+@cindex Port, block read/write
The Block-string-I/O module can be accessed with:
-@smalllisp
+@lisp
(use-modules (ice-9 rw))
-@end smalllisp
+@end lisp
It currently contains procedures that help to implement the
@code{(scsh rw)} module in guile-scsh.
@node Default Ports
@subsection Default Ports for Input, Output and Errors
+@cindex Default ports
+@cindex Port, default
@rnindex current-input-port
@deffn {Scheme Procedure} current-input-port
@deffnx {C Function} scm_current_input_port ()
+@cindex standard input
Return the current input port. This is the default port used
-by many input procedures. Initially, @code{current-input-port}
-returns the @dfn{standard input} in Unix and C terminology.
+by many input procedures.
+
+Initially this is the @dfn{standard input} in Unix and C terminology.
+When the standard input is a tty the port is unbuffered, otherwise
+it's fully buffered.
+
+Unbuffered input is good if an application runs an interactive
+subprocess, since any type-ahead input won't go into Guile's buffer
+and be unavailable to the subprocess.
+
+Note that Guile buffering is completely separate from the tty ``line
+discipline''. In the usual cooked mode on a tty Guile only sees a
+line of input once the user presses @key{Return}.
@end deffn
@rnindex current-output-port
@deffn {Scheme Procedure} current-output-port
@deffnx {C Function} scm_current_output_port ()
+@cindex standard output
Return the current output port. This is the default port used
-by many output procedures. Initially,
-@code{current-output-port} returns the @dfn{standard output} in
-Unix and C terminology.
+by many output procedures.
+
+Initially this is the @dfn{standard output} in Unix and C terminology.
+When the standard output is a tty this port is unbuffered, otherwise
+it's fully buffered.
+
+Unbuffered output to a tty is good for ensuring progress output or a
+prompt is seen. But an application which always prints whole lines
+could change to line buffered, or an application with a lot of output
+could go fully buffered and perhaps make explicit @code{force-output}
+calls (@pxref{Writing}) at selected points.
@end deffn
@deffn {Scheme Procedure} current-error-port
@deffnx {C Function} scm_current_error_port ()
-Return the port to which errors and warnings should be sent (the
-@dfn{standard error} in Unix and C terminology).
+@cindex standard error output
+Return the port to which errors and warnings should be sent.
+
+Initially this is the @dfn{standard error} in Unix and C terminology.
+When the standard error is a tty this port is unbuffered, otherwise
+it's fully buffered.
@end deffn
@deffn {Scheme Procedure} set-current-input-port port
so that they use the supplied @var{port} for input or output.
@end deffn
-@deftypefn {C Function} void scm_frame_current_input_port (SCM port)
-@deftypefnx {C Function} void scm_frame_current_output_port (SCM port)
-@deftypefnx {C Function} void scm_frame_current_error_port (SCM port)
+@deftypefn {C Function} void scm_dynwind_current_input_port (SCM port)
+@deftypefnx {C Function} void scm_dynwind_current_output_port (SCM port)
+@deftypefnx {C Function} void scm_dynwind_current_error_port (SCM port)
These functions must be used inside a pair of calls to
-@code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}).
-During the dynamic extent of the frame, the indicated port is set to
+@code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
+Wind}). During the dynwind context, the indicated port is set to
@var{port}.
More precisely, the current port is swapped with a `backup' value
-whenever the frame is entered or left. The backup value is
+whenever the dynwind context is entered or left. The backup value is
initialized with the @var{port} argument.
@end deftypefn
@node Port Types
@subsection Types of Port
+@cindex Types of ports
+@cindex Port, types
[Types of port; how to make them.]
@node File Ports
@subsubsection File Ports
+@cindex File port
+@cindex Port, file
The following procedures are used to open file ports.
See also @ref{Ports and File Descriptors, open}, for an interface
(For reference, Guile leaves text versus binary up to the C library,
@code{b} here just adds @code{O_BINARY} to the underlying @code{open}
call, when that flag is available.)
+
+Also, open the file using the 8-bit character encoding "ISO-8859-1",
+ignoring any coding declaration or port encoding.
+
+Note that, when reading or writing binary data with ports, the
+bytevector ports in the @code{(rnrs io ports)} module are preferred,
+as they return vectors, and not strings (@pxref{R6RS I/O Ports}).
@end table
+If a file cannot be opened with the access
+requested, @code{open-file} throws an exception.
+
+When the file is opened, this procedure will scan for a coding
+declaration (@pxref{Character Encoding of Source Files}). If present
+will use that encoding for interpreting the file. Otherwise, the
+port's encoding will be used. To supress this behavior, open
+the file in binary mode and then set the port encoding explicitly
+using @code{set-port-encoding!}.
+
In theory we could create read/write ports which were buffered
in one direction only. However this isn't included in the
-current interfaces. If a file cannot be opened with the access
-requested, @code{open-file} throws an exception.
+current interfaces.
@end deffn
@rnindex open-input-file
@deffn {Scheme Procedure} open-input-file filename
Open @var{filename} for input. Equivalent to
-@smalllisp
+@lisp
(open-file @var{filename} "r")
-@end smalllisp
+@end lisp
@end deffn
@rnindex open-output-file
@deffn {Scheme Procedure} open-output-file filename
Open @var{filename} for output. Equivalent to
-@smalllisp
+@lisp
(open-file @var{filename} "w")
-@end smalllisp
+@end lisp
@end deffn
@deffn {Scheme Procedure} call-with-input-file filename proc
Open @var{filename} for input or output, and call @code{(@var{proc}
port)} with the resulting port. Return the value returned by
@var{proc}. @var{filename} is opened as per @code{open-input-file} or
-@code{open-output-file} respectively, and an error is signalled if it
+@code{open-output-file} respectively, and an error is signaled if it
cannot be opened.
When @var{proc} returns, the port is closed. If @var{proc} does not
-return (eg.@: if it throws an error), then the port might not be
+return (e.g.@: if it throws an error), then the port might not be
closed automatically, though it will be garbage collected in the usual
way if not otherwise referenced.
@end deffn
@code{current-output-port}, or @code{current-error-port}. Return the
value returned by @var{thunk}. @var{filename} is opened as per
@code{open-input-file} or @code{open-output-file} respectively, and an
-error is signalled if it cannot be opened.
+error is signaled if it cannot be opened.
When @var{thunk} returns, the port is closed and the previous setting
of the respective current port is restored.
Return the filename associated with @var{port}. This function returns
the strings "standard input", "standard output" and "standard error"
when called on the current input, output and error ports respectively.
+
+@var{port} must be open, @code{port-filename} cannot be used once the
+port is closed.
@end deffn
@deffn {Scheme Procedure} set-port-filename! port filename
@node String Ports
@subsubsection String Ports
+@cindex String port
+@cindex Port, string
The following allow string ports to be opened by analogy to R4R*
file port facilities:
+With string ports, the port-encoding is treated differently than other
+types of ports. When string ports are created, they do not inherit a
+character encoding from the current locale. They are given a
+default locale that allows them to handle all valid string characters.
+Typically one should not modify a string port's character encoding
+away from its default.
+
@deffn {Scheme Procedure} call-with-output-string proc
@deffnx {C Function} scm_call_with_output_string (proc)
Calls the one-argument procedure @var{proc} with a newly created output
port. When the function returns, the string composed of the characters
written into the port is returned. @var{proc} should not close the port.
+
+Note that which characters can be written to a string port depend on the port's
+encoding. The default encoding of string ports is specified by the
+@code{%default-port-encoding} fluid (@pxref{Ports,
+@code{%default-port-encoding}}). For instance, it is an error to write Greek
+letter alpha to an ISO-8859-1-encoded string port since this character cannot be
+represented with ISO-8859-1:
+
+@example
+(define alpha (integer->char #x03b1)) ; GREEK SMALL LETTER ALPHA
+
+(with-fluids ((%default-port-encoding "ISO-8859-1"))
+ (call-with-output-string
+ (lambda (p)
+ (display alpha p))))
+
+@result{}
+Throw to key `encoding-error'
+@end example
+
+Changing the string port's encoding to a Unicode-capable encoding such as UTF-8
+solves the problem.
@end deffn
@deffn {Scheme Procedure} call-with-input-string string proc
Calls the zero-argument procedure @var{thunk} with the current output
port set temporarily to a new string port. It returns a string
composed of the characters written to the current output.
+
+See @code{call-with-output-string} above for character encoding considerations.
@end deffn
@deffn {Scheme Procedure} with-input-from-string string thunk
@node Soft Ports
@subsubsection Soft Ports
+@cindex Soft port
+@cindex 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.
@node Void Ports
@subsubsection Void Ports
+@cindex Void port
+@cindex Port, void
This kind of port causes any data to be discarded when written to, and
always returns the end-of-file object when read from.
@end deffn
+@node R6RS I/O Ports
+@subsection R6RS I/O Ports
+
+@cindex R6RS
+@cindex 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}).
+
+@c FIXME: Update description when implemented.
+@emph{Note}: The implementation of this R6RS API is currently far from
+complete, notably due to the lack of support for Unicode I/O and strings.
+
+@menu
+* R6RS End-of-File:: The end-of-file object.
+* R6RS Port Manipulation:: Manipulating R6RS ports.
+* R6RS Binary Input:: Binary input.
+* R6RS Binary Output:: Binary output.
+@end menu
+
+@node R6RS End-of-File
+@subsubsection The End-of-File Object
+
+@cindex EOF
+@cindex end-of-file
+
+R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io
+ports)} module:
+
+@deffn {Scheme Procedure} eof-object? obj
+@deffnx {C Function} scm_eof_object_p (obj)
+Return true if @var{obj} is the end-of-file (EOF) object.
+@end deffn
+
+In addition, the following procedure is provided:
+
+@deffn {Scheme Procedure} eof-object
+@deffnx {C Function} scm_eof_object ()
+Return the end-of-file (EOF) object.
+
+@lisp
+(eof-object? (eof-object))
+@result{} #t
+@end lisp
+@end deffn
+
+
+@node R6RS Port Manipulation
+@subsubsection Port Manipulation
+
+The procedures listed below operate on any kind of R6RS I/O port.
+
+@deffn {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
+@var{port}. If @var{port} does not support this operation, an error
+condition is raised.
+
+This is similar to Guile's @code{seek} procedure with the
+@code{SEEK_CUR} argument (@pxref{Random Access}).
+@end deffn
+
+@deffn {Scheme Procedure} port-has-port-position? port
+Return @code{#t} is @var{port} supports @code{port-position}.
+@end deffn
+
+@deffn {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
+@code{SEEK_SET} argument (@pxref{Random Access}).
+@end deffn
+
+@deffn {Scheme Procedure} port-has-set-port-position!? port
+Return @code{#t} is @var{port} supports @code{set-port-position!}.
+@end deffn
+
+@deffn {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}.
+@end deffn
+
+
+@node R6RS Binary Input
+@subsubsection Binary Input
+
+@cindex binary input
+
+R6RS binary input ports can be created with the procedures described
+below.
+
+@deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder]
+@deffnx {C Function} scm_open_bytevector_input_port (bv, transcoder)
+Return an input port whose contents are drawn from bytevector @var{bv}
+(@pxref{Bytevectors}).
+
+@c FIXME: Update description when implemented.
+The @var{transcoder} argument is currently not supported.
+@end deffn
+
+@cindex custom binary input ports
+
+@deffn {Scheme Procedure} make-custom-binary-input-port id read! get-position set-position! close
+@deffnx {C Function} scm_make_custom_binary_input_port (id, read!, get-position, set-position!, close)
+Return a new custom binary input port@footnote{This 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 @var{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 @var{port-position}.
+
+Likewise, if @var{set-position!} is not @code{#f}, it should be a
+one-argument procedure. When @var{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.
+
+Using a custom binary input port, the @code{open-bytevector-input-port}
+procedure could be implemented as follows:
+
+@lisp
+(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")))
+@result{} hello
+@end lisp
+@end deffn
+
+@cindex binary input
+Binary input is achieved using the procedures below:
+
+@deffn {Scheme Procedure} get-u8 port
+@deffnx {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.
+@end deffn
+
+@deffn {Scheme Procedure} lookahead-u8 port
+@deffnx {C Function} scm_lookahead_u8 (port)
+Like @code{get-u8} but does not update @var{port}'s position to point
+past the octet.
+@end deffn
+
+@deffn {Scheme Procedure} get-bytevector-n port count
+@deffnx {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.
+@end deffn
+
+@deffn {Scheme Procedure} get-bytevector-n! port bv start count
+@deffnx {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.
+@end deffn
+
+@deffn {Scheme Procedure} get-bytevector-some port
+@deffnx {C Function} scm_get_bytevector_some (port)
+Read from @var{port}, blocking as necessary, until data are available or
+and end-of-file is reached. Return either a new bytevector containing
+the data read or the end-of-file object.
+@end deffn
+
+@deffn {Scheme Procedure} get-bytevector-all port
+@deffnx {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).
+@end deffn
+
+@node R6RS Binary Output
+@subsubsection Binary Output
+
+Binary output ports can be created with the procedures below.
+
+@deffn {Scheme Procedure} open-bytevector-output-port [transcoder]
+@deffnx {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.
+
+@lisp
+(call-with-values
+ (lambda ()
+ (open-bytevector-output-port))
+ (lambda (port get-bytevector)
+ (display "hello" port)
+ (get-bytevector)))
+
+@result{} #vu8(104 101 108 108 111)
+@end lisp
+
+@c FIXME: Update description when implemented.
+The @var{transcoder} argument is currently not supported.
+@end deffn
+
+@cindex custom binary output ports
+
+@deffn {Scheme Procedure} make-custom-binary-output-port id write! get-position set-position! close
+@deffnx {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}}).
+@end deffn
+
+@cindex binary output
+Writing to a binary output port can be done using the following
+procedures:
+
+@deffn {Scheme Procedure} put-u8 port octet
+@deffnx {C Function} scm_put_u8 (port, octet)
+Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
+binary output port.
+@end deffn
+
+@deffn {Scheme Procedure} put-bytevector port bv [start [count]]
+@deffnx {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.
+@end deffn
+
+
@node I/O Extensions
@subsection Using and Extending Ports in C
@node C Port Interface
@subsubsection C Port Interface
+@cindex C port interface
+@cindex Port, C interface
This section describes how to use Scheme ports from C.
@subsubheading Port basics
+@cindex ptob
+@tindex scm_ptob_descriptor
+@tindex scm_port
+@findex SCM_PTAB_ENTRY
+@findex SCM_PTOBNUM
+@vindex scm_ptobs
There are two main data structures. A port type object (ptob) is of
type @code{scm_ptob_descriptor}. A port instance is of type
@code{scm_port}. Given an @code{SCM} variable which points to a port,
@node Port Implementation
@subsubsection Port Implementation
+@cindex Port implementation
This section describes how to implement a new port type in C.
a structure of type @code{scm_ptob_descriptor}. A ptob is created by
calling @code{scm_make_port_type}.
+@deftypefun scm_t_bits scm_make_port_type (char *name, int (*fill_input) (SCM port), void (*write) (SCM port, const void *data, size_t size))
+Return a new port type object. The @var{name}, @var{fill_input} and
+@var{write} parameters are initial values for those port type fields,
+as described below. The other fields are initialized with default
+values and can be changed later.
+@end deftypefun
+
All of the elements of the ptob, apart from @code{name}, are procedures
which collectively implement the port behaviour. Creating a new port
type mostly involves writing these procedures.
-@code{scm_make_port_type} initializes three elements of the structure
-(@code{name}, @code{fill_input} and @code{write}) from its arguments.
-The remaining elements are initialized with default values and can be
-set later if required.
-
@table @code
@item name
A pointer to a NUL terminated string: the name of the port type. This
@item mark
Called during garbage collection to mark any SCM objects that a port
object may contain. It doesn't need to be set unless the port has
-@code{SCM} components. Set using @code{scm_set_port_mark}.
+@code{SCM} components. Set using
+
+@deftypefun void scm_set_port_mark (scm_t_bits tc, SCM (*mark) (SCM port))
+@end deftypefun
@item free
Called when the port is collected during gc. It
should free any resources used by the port.
-Set using @code{scm_set_port_free}.
+Set using
+
+@deftypefun void scm_set_port_free (scm_t_bits tc, size_t (*free) (SCM port))
+@end deftypefun
@item print
Called when @code{write} is called on the port object, to print a
-port description. e.g., for an fport it may produce something like:
-@code{#<input: /etc/passwd 3>}. Set using @code{scm_set_port_print}.
+port description. E.g., for an fport it may produce something like:
+@code{#<input: /etc/passwd 3>}. Set using
+
+@deftypefun void scm_set_port_print (scm_t_bits tc, int (*print) (SCM port, SCM dest_port, scm_print_state *pstate))
+The first argument @var{port} is the object being printed, the second
+argument @var{dest_port} is where its description should go.
+@end deftypefun
@item equalp
-Not used at present. Set using @code{scm_set_port_equalp}.
+Not used at present. Set using
+
+@deftypefun void scm_set_port_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM))
+@end deftypefun
@item close
Called when the port is closed, unless it was collected during gc. It
should free any resources used by the port.
-Set using @code{scm_set_port_close}.
+Set using
+
+@deftypefun void scm_set_port_close (scm_t_bits tc, int (*close) (SCM port))
+@end deftypefun
@item write
Accept data which is to be written using the port. The port implementation
@item flush
Complete the processing of buffered output data. Reset the value of
@code{rw_active} to @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_flush}.
+Set using
+
+@deftypefun void scm_set_port_flush (scm_t_bits tc, void (*flush) (SCM port))
+@end deftypefun
@item end_input
Perform any synchronization required when switching from input to output
on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_end_input}.
+Set using
+
+@deftypefun void scm_set_port_end_input (scm_t_bits tc, void (*end_input) (SCM port, int offset))
+@end deftypefun
@item fill_input
Read new data into the read buffer and return the first character. It
Return a lower bound on the number of bytes that could be read from the
port without blocking. It can be assumed that the current state of
@code{rw_active} is @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_input_waiting}.
+Set using
+
+@deftypefun void scm_set_port_input_waiting (scm_t_bits tc, int (*input_waiting) (SCM port))
+@end deftypefun
@item seek
Set the current position of the port. The procedure can not make
like:
@example
- if (pt->rw_active == SCM_PORT_READ)
- scm_end_input (object);
- else if (pt->rw_active == SCM_PORT_WRITE)
- ptob->flush (object);
+if (pt->rw_active == SCM_PORT_READ)
+ scm_end_input (port);
+else if (pt->rw_active == SCM_PORT_WRITE)
+ ptob->flush (port);
@end example
However note that this will have the side effect of discarding any data
@code{(seek p 0 SEEK_CUR)}. The libguile fport and string port
implementations take care to avoid this problem.
-The procedure is set using @code{scm_set_port_seek}.
+The procedure is set using
+
+@deftypefun void scm_set_port_seek (scm_t_bits tc, scm_t_off (*seek) (SCM port, scm_t_off offset, int whence))
+@end deftypefun
@item truncate
Truncate the port data to be specified length. It can be assumed that the
current state of @code{rw_active} is @code{SCM_PORT_NEITHER}.
-Set using @code{scm_set_port_truncate}.
+Set using
+
+@deftypefun void scm_set_port_truncate (scm_t_bits tc, void (*truncate) (SCM port, scm_t_off length))
+@end deftypefun
@end table
HCoop / bpt / guile.git / blobdiff