2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009,
4 @c 2010, 2011, 2013 Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
8 @section Input and Output
11 * Ports:: The idea of the port abstraction.
12 * Reading:: Procedures for reading from a port.
13 * Writing:: Procedures for writing to a port.
14 * Closing:: Procedures to close a port.
15 * Random Access:: Moving around a random access port.
16 * Line/Delimited:: Read and write lines or delimited text.
17 * Block Reading and Writing:: Reading and writing blocks of text.
18 * Default Ports:: Defaults for input, output and errors.
19 * Port Types:: Types of port and how to make them.
20 * R6RS I/O Ports:: The R6RS port API.
21 * I/O Extensions:: Using and extending ports in C.
22 * BOM Handling:: Handling of Unicode byte order marks.
30 Sequential input/output in Scheme is represented by operations on a
31 @dfn{port}. This chapter explains the operations that Guile provides
32 for working with ports.
34 Ports are created by opening, for instance @code{open-file} for a file
35 (@pxref{File Ports}). Characters can be read from an input port and
36 written to an output port, or both on an input/output port. A port
37 can be closed (@pxref{Closing}) when no longer required, after which
38 any attempt to read or write is an error.
40 The formal definition of a port is very generic: an input port is
41 simply ``an object which can deliver characters on demand,'' and an
42 output port is ``an object which can accept characters.'' Because
43 this definition is so loose, it is easy to write functions that
44 simulate ports in software. @dfn{Soft ports} and @dfn{string ports}
45 are two interesting and powerful examples of this technique.
46 (@pxref{Soft Ports}, and @ref{String Ports}.)
48 Ports are garbage collected in the usual way (@pxref{Memory
49 Management}), and will be closed at that time if not already closed.
50 In this case any errors occurring in the close will not be reported.
51 Usually a program will want to explicitly close so as to be sure all
52 its operations have been successful. Of course if a program has
53 abandoned something due to an error or other condition then closing
54 problems are probably not of interest.
56 It is strongly recommended that file ports be closed explicitly when
57 no longer required. Most systems have limits on how many files can be
58 open, both on a per-process and a system-wide basis. A program that
59 uses many files should take care not to hit those limits. The same
60 applies to similar system resources such as pipes and sockets.
62 Note that automatic garbage collection is triggered only by memory
63 consumption, not by file or other resource usage, so a program cannot
64 rely on that to keep it away from system limits. An explicit call to
65 @code{gc} can of course be relied on to pick up unreferenced ports.
66 If program flow makes it hard to be certain when to close then this
67 may be an acceptable way to control resource usage.
69 All file access uses the ``LFS'' large file support functions when
70 available, so files bigger than 2 Gbytes (@math{2^31} bytes) can be
71 read and written on a 32-bit system.
73 Each port has an associated character encoding that controls how bytes
74 read from the port are converted to characters and string and controls
75 how characters and strings written to the port are converted to bytes.
76 When ports are created, they inherit their character encoding from the
77 current locale, but, that can be modified after the port is created.
79 Currently, the ports only work with @emph{non-modal} encodings. Most
80 encodings are non-modal, meaning that the conversion of bytes to a
81 string doesn't depend on its context: the same byte sequence will always
82 return the same string. A couple of modal encodings are in common use,
83 like ISO-2022-JP and ISO-2022-KR, and they are not yet supported.
85 Each port also has an associated conversion strategy: what to do when
86 a Guile character can't be converted to the port's encoded character
87 representation for output. There are three possible strategies: to
88 raise an error, to replace the character with a hex escape, or to
89 replace the character with a substitute character.
92 @deffn {Scheme Procedure} input-port? x
93 @deffnx {C Function} scm_input_port_p (x)
94 Return @code{#t} if @var{x} is an input port, otherwise return
95 @code{#f}. Any object satisfying this predicate also satisfies
100 @deffn {Scheme Procedure} output-port? x
101 @deffnx {C Function} scm_output_port_p (x)
102 Return @code{#t} if @var{x} is an output port, otherwise return
103 @code{#f}. Any object satisfying this predicate also satisfies
107 @deffn {Scheme Procedure} port? x
108 @deffnx {C Function} scm_port_p (x)
109 Return a boolean indicating whether @var{x} is a port.
110 Equivalent to @code{(or (input-port? @var{x}) (output-port?
114 @deffn {Scheme Procedure} set-port-encoding! port enc
115 @deffnx {C Function} scm_set_port_encoding_x (port, enc)
116 Sets the character encoding that will be used to interpret all port I/O.
117 @var{enc} is a string containing the name of an encoding. Valid
118 encoding names are those
119 @url{http://www.iana.org/assignments/character-sets, defined by IANA}.
122 @defvr {Scheme Variable} %default-port-encoding
123 A fluid containing @code{#f} or the name of the encoding to
124 be used by default for newly created ports (@pxref{Fluids and Dynamic
125 States}). The value @code{#f} is equivalent to @code{"ISO-8859-1"}.
127 New ports are created with the encoding appropriate for the current
128 locale if @code{setlocale} has been called or the value specified by
129 this fluid otherwise.
132 @deffn {Scheme Procedure} port-encoding port
133 @deffnx {C Function} scm_port_encoding (port)
134 Returns, as a string, the character encoding that @var{port} uses to interpret
135 its input and output. The value @code{#f} is equivalent to @code{"ISO-8859-1"}.
138 @deffn {Scheme Procedure} set-port-conversion-strategy! port sym
139 @deffnx {C Function} scm_set_port_conversion_strategy_x (port, sym)
140 Sets the behavior of the interpreter when outputting a character that
141 is not representable in the port's current encoding. @var{sym} can be
142 either @code{'error}, @code{'substitute}, or @code{'escape}. If it is
143 @code{'error}, an error will be thrown when an nonconvertible character
144 is encountered. If it is @code{'substitute}, then nonconvertible
145 characters will be replaced with approximate characters, or with
146 question marks if no approximately correct character is available. If
147 it is @code{'escape}, it will appear as a hex escape when output.
149 If @var{port} is an open port, the conversion error behavior
150 is set for that port. If it is @code{#f}, it is set as the
151 default behavior for any future ports that get created in
155 @deffn {Scheme Procedure} port-conversion-strategy port
156 @deffnx {C Function} scm_port_conversion_strategy (port)
157 Returns the behavior of the port when outputting a character that is
158 not representable in the port's current encoding. It returns the
159 symbol @code{error} if unrepresentable characters should cause
160 exceptions, @code{substitute} if the port should try to replace
161 unrepresentable characters with question marks or approximate
162 characters, or @code{escape} if unrepresentable characters should be
163 converted to string escapes.
165 If @var{port} is @code{#f}, then the current default behavior will be
166 returned. New ports will have this default behavior when they are
170 @deffn {Scheme Variable} %default-port-conversion-strategy
171 The fluid that defines the conversion strategy for newly created ports,
172 and for other conversion routines such as @code{scm_to_stringn},
173 @code{scm_from_stringn}, @code{string->pointer}, and
174 @code{pointer->string}.
176 Its value must be one of the symbols described above, with the same
177 semantics: @code{'error}, @code{'substitute}, or @code{'escape}.
179 When Guile starts, its value is @code{'substitute}.
181 Note that @code{(set-port-conversion-strategy! #f @var{sym})} is
182 equivalent to @code{(fluid-set! %default-port-conversion-strategy
191 [Generic procedures for reading from ports.]
193 These procedures pertain to reading characters and strings from
194 ports. To read general S-expressions from ports, @xref{Scheme Read}.
197 @cindex End of file object
198 @deffn {Scheme Procedure} eof-object? x
199 @deffnx {C Function} scm_eof_object_p (x)
200 Return @code{#t} if @var{x} is an end-of-file object; otherwise
205 @deffn {Scheme Procedure} char-ready? [port]
206 @deffnx {C Function} scm_char_ready_p (port)
207 Return @code{#t} if a character is ready on input @var{port}
208 and return @code{#f} otherwise. If @code{char-ready?} returns
209 @code{#t} then the next @code{read-char} operation on
210 @var{port} is guaranteed not to hang. If @var{port} is a file
211 port at end of file then @code{char-ready?} returns @code{#t}.
213 @code{char-ready?} exists to make it possible for a
214 program to accept characters from interactive ports without
215 getting stuck waiting for input. Any input editors associated
216 with such ports must make sure that characters whose existence
217 has been asserted by @code{char-ready?} cannot be rubbed out.
218 If @code{char-ready?} were to return @code{#f} at end of file,
219 a port at end of file would be indistinguishable from an
220 interactive port that has no ready characters.
224 @deffn {Scheme Procedure} read-char [port]
225 @deffnx {C Function} scm_read_char (port)
226 Return the next character available from @var{port}, updating
227 @var{port} to point to the following character. If no more
228 characters are available, the end-of-file object is returned.
230 When @var{port}'s data cannot be decoded according to its
231 character encoding, a @code{decoding-error} is raised and
232 @var{port} points past the erroneous byte sequence.
235 @deftypefn {C Function} size_t scm_c_read (SCM port, void *buffer, size_t size)
236 Read up to @var{size} bytes from @var{port} and store them in
237 @var{buffer}. The return value is the number of bytes actually read,
238 which can be less than @var{size} if end-of-file has been reached.
240 Note that this function does not update @code{port-line} and
241 @code{port-column} below.
245 @deffn {Scheme Procedure} peek-char [port]
246 @deffnx {C Function} scm_peek_char (port)
247 Return the next character available from @var{port},
248 @emph{without} updating @var{port} to point to the following
249 character. If no more characters are available, the
250 end-of-file object is returned.
252 The value returned by
253 a call to @code{peek-char} is the same as the value that would
254 have been returned by a call to @code{read-char} on the same
255 port. The only difference is that the very next call to
256 @code{read-char} or @code{peek-char} on that @var{port} will
257 return the value returned by the preceding call to
258 @code{peek-char}. In particular, a call to @code{peek-char} on
259 an interactive port will hang waiting for input whenever a call
260 to @code{read-char} would have hung.
262 As for @code{read-char}, a @code{decoding-error} may be raised
263 if such a situation occurs. However, unlike with @code{read-char},
264 @var{port} still points at the beginning of the erroneous byte
265 sequence when the error is raised.
268 @deffn {Scheme Procedure} unread-char cobj [port]
269 @deffnx {C Function} scm_unread_char (cobj, port)
270 Place character @var{cobj} in @var{port} so that it will be read by the
271 next read operation. If called multiple times, the unread characters
272 will be read again in last-in first-out order. If @var{port} is
273 not supplied, the current input port is used.
276 @deffn {Scheme Procedure} unread-string str port
277 @deffnx {C Function} scm_unread_string (str, port)
278 Place the string @var{str} in @var{port} so that its characters will
279 be read from left-to-right as the next characters from @var{port}
280 during subsequent read operations. If called multiple times, the
281 unread characters will be read again in last-in first-out order. If
282 @var{port} is not supplied, the @code{current-input-port} is used.
285 @deffn {Scheme Procedure} drain-input port
286 @deffnx {C Function} scm_drain_input (port)
287 This procedure clears a port's input buffers, similar
288 to the way that force-output clears the output buffer. The
289 contents of the buffers are returned as a single string, e.g.,
292 (define p (open-input-file ...))
293 (drain-input p) => empty string, nothing buffered yet.
294 (unread-char (read-char p) p)
295 (drain-input p) => initial chars from p, up to the buffer size.
298 Draining the buffers may be useful for cleanly finishing
299 buffered I/O so that the file descriptor can be used directly
303 @deffn {Scheme Procedure} port-column port
304 @deffnx {Scheme Procedure} port-line port
305 @deffnx {C Function} scm_port_column (port)
306 @deffnx {C Function} scm_port_line (port)
307 Return the current column number or line number of @var{port}.
309 unknown, the result is #f. Otherwise, the result is a 0-origin integer
310 - i.e.@: the first character of the first line is line 0, column 0.
311 (However, when you display a file position, for example in an error
312 message, we recommend you add 1 to get 1-origin integers. This is
313 because lines and column numbers traditionally start with 1, and that is
314 what non-programmers will find most natural.)
317 @deffn {Scheme Procedure} set-port-column! port column
318 @deffnx {Scheme Procedure} set-port-line! port line
319 @deffnx {C Function} scm_set_port_column_x (port, column)
320 @deffnx {C Function} scm_set_port_line_x (port, line)
321 Set the current column or line number of @var{port}.
328 [Generic procedures for writing to ports.]
330 These procedures are for writing characters and strings to
331 ports. For more information on writing arbitrary Scheme objects to
332 ports, @xref{Scheme Write}.
334 @deffn {Scheme Procedure} get-print-state port
335 @deffnx {C Function} scm_get_print_state (port)
336 Return the print state of the port @var{port}. If @var{port}
337 has no associated print state, @code{#f} is returned.
341 @deffn {Scheme Procedure} newline [port]
342 @deffnx {C Function} scm_newline (port)
343 Send a newline to @var{port}.
344 If @var{port} is omitted, send to the current output port.
347 @deffn {Scheme Procedure} port-with-print-state port [pstate]
348 @deffnx {C Function} scm_port_with_print_state (port, pstate)
349 Create a new port which behaves like @var{port}, but with an
350 included print state @var{pstate}. @var{pstate} is optional.
351 If @var{pstate} isn't supplied and @var{port} already has
352 a print state, the old print state is reused.
355 @deffn {Scheme Procedure} simple-format destination message . args
356 @deffnx {C Function} scm_simple_format (destination, message, args)
357 Write @var{message} to @var{destination}, defaulting to
358 the current output port.
359 @var{message} can contain @code{~A} (was @code{%s}) and
360 @code{~S} (was @code{%S}) escapes. When printed,
361 the escapes are replaced with corresponding members of
363 @code{~A} formats using @code{display} and @code{~S} formats
365 If @var{destination} is @code{#t}, then use the current output
366 port, if @var{destination} is @code{#f}, then return a string
367 containing the formatted text. Does not add a trailing newline.
371 @deffn {Scheme Procedure} write-char chr [port]
372 @deffnx {C Function} scm_write_char (chr, port)
373 Send character @var{chr} to @var{port}.
376 @deftypefn {C Function} void scm_c_write (SCM port, const void *buffer, size_t size)
377 Write @var{size} bytes at @var{buffer} to @var{port}.
379 Note that this function does not update @code{port-line} and
380 @code{port-column} (@pxref{Reading}).
384 @deffn {Scheme Procedure} force-output [port]
385 @deffnx {C Function} scm_force_output (port)
386 Flush the specified output port, or the current output port if @var{port}
387 is omitted. The current output buffer contents are passed to the
388 underlying port implementation (e.g., in the case of fports, the
389 data will be written to the file and the output buffer will be cleared.)
390 It has no effect on an unbuffered port.
392 The return value is unspecified.
395 @deffn {Scheme Procedure} flush-all-ports
396 @deffnx {C Function} scm_flush_all_ports ()
397 Equivalent to calling @code{force-output} on
398 all open output ports. The return value is unspecified.
404 @cindex Closing ports
407 @deffn {Scheme Procedure} close-port port
408 @deffnx {C Function} scm_close_port (port)
409 Close the specified port object. Return @code{#t} if it
410 successfully closes a port or @code{#f} if it was already
411 closed. An exception may be raised if an error occurs, for
412 example when flushing buffered output. See also @ref{Ports and
413 File Descriptors, close}, for a procedure which can close file
417 @deffn {Scheme Procedure} close-input-port port
418 @deffnx {Scheme Procedure} close-output-port port
419 @deffnx {C Function} scm_close_input_port (port)
420 @deffnx {C Function} scm_close_output_port (port)
421 @rnindex close-input-port
422 @rnindex close-output-port
423 Close the specified input or output @var{port}. An exception may be
424 raised if an error occurs while closing. If @var{port} is already
425 closed, nothing is done. The return value is unspecified.
427 See also @ref{Ports and File Descriptors, close}, for a procedure
428 which can close file descriptors.
431 @deffn {Scheme Procedure} port-closed? port
432 @deffnx {C Function} scm_port_closed_p (port)
433 Return @code{#t} if @var{port} is closed or @code{#f} if it is
439 @subsection Random Access
440 @cindex Random access, ports
441 @cindex Port, random access
443 @deffn {Scheme Procedure} seek fd_port offset whence
444 @deffnx {C Function} scm_seek (fd_port, offset, whence)
445 Sets the current position of @var{fd_port} to the integer
446 @var{offset}. For a file port, @var{offset} is expressed
447 as a number of bytes; for other types of ports, such as string
448 ports, @var{offset} is an abstract representation of the
449 position within the port's data, not necessarily expressed
450 as a number of bytes. @var{offset} is interpreted according to
451 the value of @var{whence}.
453 One of the following variables should be supplied for
456 Seek from the beginning of the file.
459 Seek from the current position.
462 Seek from the end of the file.
464 If @var{fd_port} is a file descriptor, the underlying system
465 call is @code{lseek}. @var{port} may be a string port.
467 The value returned is the new position in @var{fd_port}. This means
468 that the current position of a port can be obtained using:
470 (seek port 0 SEEK_CUR)
474 @deffn {Scheme Procedure} ftell fd_port
475 @deffnx {C Function} scm_ftell (fd_port)
476 Return an integer representing the current position of
477 @var{fd_port}, measured from the beginning. Equivalent to:
480 (seek port 0 SEEK_CUR)
486 @deffn {Scheme Procedure} truncate-file file [length]
487 @deffnx {C Function} scm_truncate_file (file, length)
488 Truncate @var{file} to @var{length} bytes. @var{file} can be a
489 filename string, a port object, or an integer file descriptor. The
490 return value is unspecified.
492 For a port or file descriptor @var{length} can be omitted, in which
493 case the file is truncated at the current position (per @code{ftell}
496 On most systems a file can be extended by giving a length greater than
497 the current size, but this is not mandatory in the POSIX standard.
501 @subsection Line Oriented and Delimited Text
502 @cindex Line input/output
503 @cindex Port, line input/output
505 The delimited-I/O module can be accessed with:
508 (use-modules (ice-9 rdelim))
511 It can be used to read or write lines of text, or read text delimited by
512 a specified set of characters. It's similar to the @code{(scsh rdelim)}
513 module from guile-scsh, but does not use multiple values or character
514 sets and has an extra procedure @code{write-line}.
516 @c begin (scm-doc-string "rdelim.scm" "read-line")
517 @deffn {Scheme Procedure} read-line [port] [handle-delim]
518 Return a line of text from @var{port} if specified, otherwise from the
519 value returned by @code{(current-input-port)}. Under Unix, a line of text
520 is terminated by the first end-of-line character or by end-of-file.
522 If @var{handle-delim} is specified, it should be one of the following
526 Discard the terminating delimiter. This is the default, but it will
527 be impossible to tell whether the read terminated with a delimiter or
530 Append the terminating delimiter (if any) to the returned string.
532 Push the terminating delimiter (if any) back on to the port.
534 Return a pair containing the string read from the port and the
535 terminating delimiter or end-of-file object.
538 Like @code{read-char}, this procedure can throw to @code{decoding-error}
539 (@pxref{Reading, @code{read-char}}).
542 @c begin (scm-doc-string "rdelim.scm" "read-line!")
543 @deffn {Scheme Procedure} read-line! buf [port]
544 Read a line of text into the supplied string @var{buf} and return the
545 number of characters added to @var{buf}. If @var{buf} is filled, then
546 @code{#f} is returned.
547 Read from @var{port} if
548 specified, otherwise from the value returned by @code{(current-input-port)}.
551 @c begin (scm-doc-string "rdelim.scm" "read-delimited")
552 @deffn {Scheme Procedure} read-delimited delims [port] [handle-delim]
553 Read text until one of the characters in the string @var{delims} is found
554 or end-of-file is reached. Read from @var{port} if supplied, otherwise
555 from the value returned by @code{(current-input-port)}.
556 @var{handle-delim} takes the same values as described for @code{read-line}.
559 @c begin (scm-doc-string "rdelim.scm" "read-delimited!")
560 @deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end]
561 Read text into the supplied string @var{buf}.
563 If a delimiter was found, return the number of characters written,
564 except if @var{handle-delim} is @code{split}, in which case the return
565 value is a pair, as noted above.
567 As a special case, if @var{port} was already at end-of-stream, the EOF
568 object is returned. Also, if no characters were written because the
569 buffer was full, @code{#f} is returned.
571 It's something of a wacky interface, to be honest.
574 @deffn {Scheme Procedure} write-line obj [port]
575 @deffnx {C Function} scm_write_line (obj, port)
576 Display @var{obj} and a newline character to @var{port}. If
577 @var{port} is not specified, @code{(current-output-port)} is
578 used. This function is equivalent to:
585 In the past, Guile did not have a procedure that would just read out all
586 of the characters from a port. As a workaround, many people just called
587 @code{read-delimited} with no delimiters, knowing that would produce the
588 behavior they wanted. This prompted Guile developers to add some
589 routines that would read all characters from a port. So it is that
590 @code{(ice-9 rdelim)} is also the home for procedures that can reading
593 @deffn {Scheme Procedure} read-string [port] [count]
594 Read all of the characters out of @var{port} and return them as a
595 string. If the @var{count} is present, treat it as a limit to the
596 number of characters to read.
598 By default, read from the current input port, with no size limit on the
599 result. This procedure always returns a string, even if no characters
603 @deffn {Scheme Procedure} read-string! buf [port] [start] [end]
604 Fill @var{buf} with characters read from @var{port}, defaulting to the
605 current input port. Return the number of characters read.
607 If @var{start} or @var{end} are specified, store data only into the
608 substring of @var{str} bounded by @var{start} and @var{end} (which
609 default to the beginning and end of the string, respectively).
612 Some of the aforementioned I/O functions rely on the following C
613 primitives. These will mainly be of interest to people hacking Guile
616 @deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]]
617 @deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end)
618 Read characters from @var{port} into @var{str} until one of the
619 characters in the @var{delims} string is encountered. If
620 @var{gobble} is true, discard the delimiter character;
621 otherwise, leave it in the input stream for the next read. If
622 @var{port} is not specified, use the value of
623 @code{(current-input-port)}. If @var{start} or @var{end} are
624 specified, store data only into the substring of @var{str}
625 bounded by @var{start} and @var{end} (which default to the
626 beginning and end of the string, respectively).
628 Return a pair consisting of the delimiter that terminated the
629 string and the number of characters read. If reading stopped
630 at the end of file, the delimiter returned is the
631 @var{eof-object}; if the string was filled without encountering
632 a delimiter, this value is @code{#f}.
635 @deffn {Scheme Procedure} %read-line [port]
636 @deffnx {C Function} scm_read_line (port)
637 Read a newline-terminated line from @var{port}, allocating storage as
638 necessary. The newline terminator (if any) is removed from the string,
639 and a pair consisting of the line and its delimiter is returned. The
640 delimiter may be either a newline or the @var{eof-object}; if
641 @code{%read-line} is called at the end of file, it returns the pair
642 @code{(#<eof> . #<eof>)}.
645 @node Block Reading and Writing
646 @subsection Block reading and writing
647 @cindex Block read/write
648 @cindex Port, block read/write
650 The Block-string-I/O module can be accessed with:
653 (use-modules (ice-9 rw))
656 It currently contains procedures that help to implement the
657 @code{(scsh rw)} module in guile-scsh.
659 @deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]]
660 @deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end)
661 Read characters from a port or file descriptor into a
662 string @var{str}. A port must have an underlying file
663 descriptor --- a so-called fport. This procedure is
664 scsh-compatible and can efficiently read large strings.
669 attempt to fill the entire string, unless the @var{start}
670 and/or @var{end} arguments are supplied. i.e., @var{start}
671 defaults to 0 and @var{end} defaults to
672 @code{(string-length str)}
674 use the current input port if @var{port_or_fdes} is not
677 return fewer than the requested number of characters in some
678 cases, e.g., on end of file, if interrupted by a signal, or if
679 not all the characters are immediately available.
681 wait indefinitely for some input if no characters are
683 unless the port is in non-blocking mode.
685 read characters from the port's input buffers if available,
686 instead from the underlying file descriptor.
688 return @code{#f} if end-of-file is encountered before reading
689 any characters, otherwise return the number of characters
692 return 0 if the port is in non-blocking mode and no characters
693 are immediately available.
695 return 0 if the request is for 0 bytes, with no
700 @deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]]
701 @deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end)
702 Write characters from a string @var{str} to a port or file
703 descriptor. A port must have an underlying file descriptor
704 --- a so-called fport. This procedure is
705 scsh-compatible and can efficiently write large strings.
710 attempt to write the entire string, unless the @var{start}
711 and/or @var{end} arguments are supplied. i.e., @var{start}
712 defaults to 0 and @var{end} defaults to
713 @code{(string-length str)}
715 use the current output port if @var{port_of_fdes} is not
718 in the case of a buffered port, store the characters in the
719 port's output buffer, if all will fit. If they will not fit
720 then any existing buffered characters will be flushed
722 to write the new characters directly to the underlying file
723 descriptor. If the port is in non-blocking mode and
724 buffered characters can not be flushed immediately, then an
725 @code{EAGAIN} system-error exception will be raised (Note:
726 scsh does not support the use of non-blocking buffered ports.)
728 write fewer than the requested number of
729 characters in some cases, e.g., if interrupted by a signal or
730 if not all of the output can be accepted immediately.
732 wait indefinitely for at least one character
733 from @var{str} to be accepted by the port, unless the port is
734 in non-blocking mode.
736 return the number of characters accepted by the port.
738 return 0 if the port is in non-blocking mode and can not accept
739 at least one character from @var{str} immediately
741 return 0 immediately if the request size is 0 bytes.
746 @subsection Default Ports for Input, Output and Errors
747 @cindex Default ports
748 @cindex Port, default
750 @rnindex current-input-port
751 @deffn {Scheme Procedure} current-input-port
752 @deffnx {C Function} scm_current_input_port ()
753 @cindex standard input
754 Return the current input port. This is the default port used
755 by many input procedures.
757 Initially this is the @dfn{standard input} in Unix and C terminology.
758 When the standard input is a tty the port is unbuffered, otherwise
761 Unbuffered input is good if an application runs an interactive
762 subprocess, since any type-ahead input won't go into Guile's buffer
763 and be unavailable to the subprocess.
765 Note that Guile buffering is completely separate from the tty ``line
766 discipline''. In the usual cooked mode on a tty Guile only sees a
767 line of input once the user presses @key{Return}.
770 @rnindex current-output-port
771 @deffn {Scheme Procedure} current-output-port
772 @deffnx {C Function} scm_current_output_port ()
773 @cindex standard output
774 Return the current output port. This is the default port used
775 by many output procedures.
777 Initially this is the @dfn{standard output} in Unix and C terminology.
778 When the standard output is a tty this port is unbuffered, otherwise
781 Unbuffered output to a tty is good for ensuring progress output or a
782 prompt is seen. But an application which always prints whole lines
783 could change to line buffered, or an application with a lot of output
784 could go fully buffered and perhaps make explicit @code{force-output}
785 calls (@pxref{Writing}) at selected points.
788 @deffn {Scheme Procedure} current-error-port
789 @deffnx {C Function} scm_current_error_port ()
790 @cindex standard error output
791 Return the port to which errors and warnings should be sent.
793 Initially this is the @dfn{standard error} in Unix and C terminology.
794 When the standard error is a tty this port is unbuffered, otherwise
798 @deffn {Scheme Procedure} set-current-input-port port
799 @deffnx {Scheme Procedure} set-current-output-port port
800 @deffnx {Scheme Procedure} set-current-error-port port
801 @deffnx {C Function} scm_set_current_input_port (port)
802 @deffnx {C Function} scm_set_current_output_port (port)
803 @deffnx {C Function} scm_set_current_error_port (port)
804 Change the ports returned by @code{current-input-port},
805 @code{current-output-port} and @code{current-error-port}, respectively,
806 so that they use the supplied @var{port} for input or output.
809 @deftypefn {C Function} void scm_dynwind_current_input_port (SCM port)
810 @deftypefnx {C Function} void scm_dynwind_current_output_port (SCM port)
811 @deftypefnx {C Function} void scm_dynwind_current_error_port (SCM port)
812 These functions must be used inside a pair of calls to
813 @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
814 Wind}). During the dynwind context, the indicated port is set to
817 More precisely, the current port is swapped with a `backup' value
818 whenever the dynwind context is entered or left. The backup value is
819 initialized with the @var{port} argument.
823 @subsection Types of Port
824 @cindex Types of ports
827 [Types of port; how to make them.]
830 * File Ports:: Ports on an operating system file.
831 * String Ports:: Ports on a Scheme string.
832 * Soft Ports:: Ports on arbitrary Scheme procedures.
833 * Void Ports:: Ports on nothing at all.
838 @subsubsection File Ports
842 The following procedures are used to open file ports.
843 See also @ref{Ports and File Descriptors, open}, for an interface
844 to the Unix @code{open} system call.
846 Most systems have limits on how many files can be open, so it's
847 strongly recommended that file ports be closed explicitly when no
848 longer required (@pxref{Ports}).
850 @deffn {Scheme Procedure} open-file filename mode @
851 [#:guess-encoding=#f] [#:encoding=#f]
852 @deffnx {C Function} scm_open_file_with_encoding @
853 (filename, mode, guess_encoding, encoding)
854 @deffnx {C Function} scm_open_file (filename, mode)
855 Open the file whose name is @var{filename}, and return a port
856 representing that file. The attributes of the port are
857 determined by the @var{mode} string. The way in which this is
858 interpreted is similar to C stdio. The first character must be
859 one of the following:
863 Open an existing file for input.
865 Open a file for output, creating it if it doesn't already exist
866 or removing its contents if it does.
868 Open a file for output, creating it if it doesn't already
869 exist. All writes to the port will go to the end of the file.
870 The "append mode" can be turned off while the port is in use
871 @pxref{Ports and File Descriptors, fcntl}
874 The following additional characters can be appended:
878 Open the port for both input and output. E.g., @code{r+}: open
879 an existing file for both input and output.
881 Create an "unbuffered" port. In this case input and output
882 operations are passed directly to the underlying port
883 implementation without additional buffering. This is likely to
884 slow down I/O operations. The buffering mode can be changed
885 while a port is in use @pxref{Ports and File Descriptors,
888 Add line-buffering to the port. The port output buffer will be
889 automatically flushed whenever a newline character is written.
891 Use binary mode, ensuring that each byte in the file will be read as one
894 To provide this property, the file will be opened with the 8-bit
895 character encoding "ISO-8859-1", ignoring the default port encoding.
896 @xref{Ports}, for more information on port encodings.
898 Note that while it is possible to read and write binary data as
899 characters or strings, it is usually better to treat bytes as octets,
900 and byte sequences as bytevectors. @xref{R6RS Binary Input}, and
901 @ref{R6RS Binary Output}, for more.
903 This option had another historical meaning, for DOS compatibility: in
904 the default (textual) mode, DOS reads a CR-LF sequence as one LF byte.
905 The @code{b} flag prevents this from happening, adding @code{O_BINARY}
906 to the underlying @code{open} call. Still, the flag is generally useful
907 because of its port encoding ramifications.
910 Unless binary mode is requested, the character encoding of the new port
911 is determined as follows: First, if @var{guess-encoding} is true, the
912 @code{file-encoding} procedure is used to guess the encoding of the file
913 (@pxref{Character Encoding of Source Files}). If @var{guess-encoding}
914 is false or if @code{file-encoding} fails, @var{encoding} is used unless
915 it is also false. As a last resort, the default port encoding is used.
916 @xref{Ports}, for more information on port encodings. It is an error to
917 pass a non-false @var{guess-encoding} or @var{encoding} if binary mode
920 If a file cannot be opened with the access requested, @code{open-file}
923 When the file is opened, its encoding is set to the current
924 @code{%default-port-encoding}, unless the @code{b} flag was supplied.
925 Sometimes it is desirable to honor Emacs-style coding declarations in
926 files@footnote{Guile 2.0.0 to 2.0.7 would do this by default. This
927 behavior was deemed inappropriate and disabled starting from Guile
928 2.0.8.}. When that is the case, the @code{file-encoding} procedure can
929 be used as follows (@pxref{Character Encoding of Source Files,
930 @code{file-encoding}}):
933 (let* ((port (open-input-file file))
934 (encoding (file-encoding port)))
935 (set-port-encoding! port (or encoding (port-encoding port))))
938 In theory we could create read/write ports which were buffered
939 in one direction only. However this isn't included in the
943 @rnindex open-input-file
944 @deffn {Scheme Procedure} open-input-file filename @
945 [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]
947 Open @var{filename} for input. If @var{binary} is true, open the port
948 in binary mode, otherwise use text mode. @var{encoding} and
949 @var{guess-encoding} determine the character encoding as described above
950 for @code{open-file}. Equivalent to
952 (open-file @var{filename}
953 (if @var{binary} "rb" "r")
954 #:guess-encoding @var{guess-encoding}
955 #:encoding @var{encoding})
959 @rnindex open-output-file
960 @deffn {Scheme Procedure} open-output-file filename @
961 [#:encoding=#f] [#:binary=#f]
963 Open @var{filename} for output. If @var{binary} is true, open the port
964 in binary mode, otherwise use text mode. @var{encoding} specifies the
965 character encoding as described above for @code{open-file}. Equivalent
968 (open-file @var{filename}
969 (if @var{binary} "wb" "w")
970 #:encoding @var{encoding})
974 @deffn {Scheme Procedure} call-with-input-file filename proc @
975 [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]
976 @deffnx {Scheme Procedure} call-with-output-file filename proc @
977 [#:encoding=#f] [#:binary=#f]
978 @rnindex call-with-input-file
979 @rnindex call-with-output-file
980 Open @var{filename} for input or output, and call @code{(@var{proc}
981 port)} with the resulting port. Return the value returned by
982 @var{proc}. @var{filename} is opened as per @code{open-input-file} or
983 @code{open-output-file} respectively, and an error is signaled if it
986 When @var{proc} returns, the port is closed. If @var{proc} does not
987 return (e.g.@: if it throws an error), then the port might not be
988 closed automatically, though it will be garbage collected in the usual
989 way if not otherwise referenced.
992 @deffn {Scheme Procedure} with-input-from-file filename thunk @
993 [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]
994 @deffnx {Scheme Procedure} with-output-to-file filename thunk @
995 [#:encoding=#f] [#:binary=#f]
996 @deffnx {Scheme Procedure} with-error-to-file filename thunk @
997 [#:encoding=#f] [#:binary=#f]
998 @rnindex with-input-from-file
999 @rnindex with-output-to-file
1000 Open @var{filename} and call @code{(@var{thunk})} with the new port
1001 setup as respectively the @code{current-input-port},
1002 @code{current-output-port}, or @code{current-error-port}. Return the
1003 value returned by @var{thunk}. @var{filename} is opened as per
1004 @code{open-input-file} or @code{open-output-file} respectively, and an
1005 error is signaled if it cannot be opened.
1007 When @var{thunk} returns, the port is closed and the previous setting
1008 of the respective current port is restored.
1010 The current port setting is managed with @code{dynamic-wind}, so the
1011 previous value is restored no matter how @var{thunk} exits (eg.@: an
1012 exception), and if @var{thunk} is re-entered (via a captured
1013 continuation) then it's set again to the @var{filename} port.
1015 The port is closed when @var{thunk} returns normally, but not when
1016 exited via an exception or new continuation. This ensures it's still
1017 ready for use if @var{thunk} is re-entered by a captured continuation.
1018 Of course the port is always garbage collected and closed in the usual
1019 way when no longer referenced anywhere.
1022 @deffn {Scheme Procedure} port-mode port
1023 @deffnx {C Function} scm_port_mode (port)
1024 Return the port modes associated with the open port @var{port}.
1025 These will not necessarily be identical to the modes used when
1026 the port was opened, since modes such as "append" which are
1027 used only during port creation are not retained.
1030 @deffn {Scheme Procedure} port-filename port
1031 @deffnx {C Function} scm_port_filename (port)
1032 Return the filename associated with @var{port}, or @code{#f} if no
1033 filename is associated with the port.
1035 @var{port} must be open, @code{port-filename} cannot be used once the
1039 @deffn {Scheme Procedure} set-port-filename! port filename
1040 @deffnx {C Function} scm_set_port_filename_x (port, filename)
1041 Change the filename associated with @var{port}, using the current input
1042 port if none is specified. Note that this does not change the port's
1043 source of data, but only the value that is returned by
1044 @code{port-filename} and reported in diagnostic output.
1047 @deffn {Scheme Procedure} file-port? obj
1048 @deffnx {C Function} scm_file_port_p (obj)
1049 Determine whether @var{obj} is a port that is related to a file.
1054 @subsubsection String Ports
1056 @cindex Port, string
1058 The following allow string ports to be opened by analogy to R4RS
1059 file port facilities:
1061 With string ports, the port-encoding is treated differently than other
1062 types of ports. When string ports are created, they do not inherit a
1063 character encoding from the current locale. They are given a
1064 default locale that allows them to handle all valid string characters.
1065 Typically one should not modify a string port's character encoding
1066 away from its default.
1068 @deffn {Scheme Procedure} call-with-output-string proc
1069 @deffnx {C Function} scm_call_with_output_string (proc)
1070 Calls the one-argument procedure @var{proc} with a newly created output
1071 port. When the function returns, the string composed of the characters
1072 written into the port is returned. @var{proc} should not close the port.
1075 @deffn {Scheme Procedure} call-with-input-string string proc
1076 @deffnx {C Function} scm_call_with_input_string (string, proc)
1077 Calls the one-argument procedure @var{proc} with a newly
1078 created input port from which @var{string}'s contents may be
1079 read. The value yielded by the @var{proc} is returned.
1082 @deffn {Scheme Procedure} with-output-to-string thunk
1083 Calls the zero-argument procedure @var{thunk} with the current output
1084 port set temporarily to a new string port. It returns a string
1085 composed of the characters written to the current output.
1088 @deffn {Scheme Procedure} with-input-from-string string thunk
1089 Calls the zero-argument procedure @var{thunk} with the current input
1090 port set temporarily to a string port opened on the specified
1091 @var{string}. The value yielded by @var{thunk} is returned.
1094 @deffn {Scheme Procedure} open-input-string str
1095 @deffnx {C Function} scm_open_input_string (str)
1096 Take a string and return an input port that delivers characters
1097 from the string. The port can be closed by
1098 @code{close-input-port}, though its storage will be reclaimed
1099 by the garbage collector if it becomes inaccessible.
1102 @deffn {Scheme Procedure} open-output-string
1103 @deffnx {C Function} scm_open_output_string ()
1104 Return an output port that will accumulate characters for
1105 retrieval by @code{get-output-string}. The port can be closed
1106 by the procedure @code{close-output-port}, though its storage
1107 will be reclaimed by the garbage collector if it becomes
1111 @deffn {Scheme Procedure} get-output-string port
1112 @deffnx {C Function} scm_get_output_string (port)
1113 Given an output port created by @code{open-output-string},
1114 return a string consisting of the characters that have been
1115 output to the port so far.
1117 @code{get-output-string} must be used before closing @var{port}, once
1118 closed the string cannot be obtained.
1121 A string port can be used in many procedures which accept a port
1122 but which are not dependent on implementation details of fports.
1123 E.g., seeking and truncating will work on a string port,
1124 but trying to extract the file descriptor number will fail.
1128 @subsubsection Soft Ports
1132 A @dfn{soft-port} is a port based on a vector of procedures capable of
1133 accepting or delivering characters. It allows emulation of I/O ports.
1135 @deffn {Scheme Procedure} make-soft-port pv modes
1136 @deffnx {C Function} scm_make_soft_port (pv, modes)
1137 Return a port capable of receiving or delivering characters as
1138 specified by the @var{modes} string (@pxref{File Ports,
1139 open-file}). @var{pv} must be a vector of length 5 or 6. Its
1140 components are as follows:
1144 procedure accepting one character for output
1146 procedure accepting a string for output
1148 thunk for flushing output
1150 thunk for getting one character
1152 thunk for closing port (not by garbage collection)
1154 (if present and not @code{#f}) thunk for computing the number of
1155 characters that can be read from the port without blocking.
1158 For an output-only port only elements 0, 1, 2, and 4 need be
1159 procedures. For an input-only port only elements 3 and 4 need
1160 be procedures. Thunks 2 and 4 can instead be @code{#f} if
1161 there is no useful operation for them to perform.
1163 If thunk 3 returns @code{#f} or an @code{eof-object}
1164 (@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
1165 Scheme}) it indicates that the port has reached end-of-file.
1169 (define stdout (current-output-port))
1170 (define p (make-soft-port
1172 (lambda (c) (write c stdout))
1173 (lambda (s) (display s stdout))
1174 (lambda () (display "." stdout))
1175 (lambda () (char-upcase (read-char)))
1176 (lambda () (display "@@" stdout)))
1179 (write p p) @result{} #<input-output: soft 8081e20>
1185 @subsubsection Void Ports
1189 This kind of port causes any data to be discarded when written to, and
1190 always returns the end-of-file object when read from.
1192 @deffn {Scheme Procedure} %make-void-port mode
1193 @deffnx {C Function} scm_sys_make_void_port (mode)
1194 Create and return a new void port. A void port acts like
1195 @file{/dev/null}. The @var{mode} argument
1196 specifies the input/output modes for this port: see the
1197 documentation for @code{open-file} in @ref{File Ports}.
1201 @node R6RS I/O Ports
1202 @subsection R6RS I/O Ports
1207 The I/O port API of the @uref{http://www.r6rs.org/, Revised Report^6 on
1208 the Algorithmic Language Scheme (R6RS)} is provided by the @code{(rnrs
1209 io ports)} module. It provides features, such as binary I/O and Unicode
1210 string I/O, that complement or refine Guile's historical port API
1211 presented above (@pxref{Input and Output}). Note that R6RS ports are not
1212 disjoint from Guile's native ports, so Guile-specific procedures will
1213 work on ports created using the R6RS API, and vice versa.
1215 The text in this section is taken from the R6RS standard libraries
1216 document, with only minor adaptions for inclusion in this manual. The
1217 Guile developers offer their thanks to the R6RS editors for having
1218 provided the report's text under permissive conditions making this
1221 @c FIXME: Update description when implemented.
1222 @emph{Note}: The implementation of this R6RS API is not complete yet.
1225 * R6RS File Names:: File names.
1226 * R6RS File Options:: Options for opening files.
1227 * R6RS Buffer Modes:: Influencing buffering behavior.
1228 * R6RS Transcoders:: Influencing port encoding.
1229 * R6RS End-of-File:: The end-of-file object.
1230 * R6RS Port Manipulation:: Manipulating R6RS ports.
1231 * R6RS Input Ports:: Input Ports.
1232 * R6RS Binary Input:: Binary input.
1233 * R6RS Textual Input:: Textual input.
1234 * R6RS Output Ports:: Output Ports.
1235 * R6RS Binary Output:: Binary output.
1236 * R6RS Textual Output:: Textual output.
1239 A subset of the @code{(rnrs io ports)} module, plus one non-standard
1240 procedure @code{unget-bytevector} (@pxref{R6RS Binary Input}), is
1241 provided by the @code{(ice-9 binary-ports)} module. It contains binary
1242 input/output procedures and does not rely on R6RS support.
1244 @node R6RS File Names
1245 @subsubsection File Names
1247 Some of the procedures described in this chapter accept a file name as an
1248 argument. Valid values for such a file name include strings that name a file
1249 using the native notation of file system paths on an implementation's
1250 underlying operating system, and may include implementation-dependent
1253 A @var{filename} parameter name means that the
1254 corresponding argument must be a file name.
1256 @node R6RS File Options
1257 @subsubsection File Options
1258 @cindex file options
1260 When opening a file, the various procedures in this library accept a
1261 @code{file-options} object that encapsulates flags to specify how the
1262 file is to be opened. A @code{file-options} object is an enum-set
1263 (@pxref{rnrs enums}) over the symbols constituting valid file options.
1265 A @var{file-options} parameter name means that the corresponding
1266 argument must be a file-options object.
1268 @deffn {Scheme Syntax} file-options @var{file-options-symbol} ...
1270 Each @var{file-options-symbol} must be a symbol.
1272 The @code{file-options} syntax returns a file-options object that
1273 encapsulates the specified options.
1275 When supplied to an operation that opens a file for output, the
1276 file-options object returned by @code{(file-options)} specifies that the
1277 file is created if it does not exist and an exception with condition
1278 type @code{&i/o-file-already-exists} is raised if it does exist. The
1279 following standard options can be included to modify the default
1284 If the file does not already exist, it is not created;
1285 instead, an exception with condition type @code{&i/o-file-does-not-exist}
1287 If the file already exists, the exception with condition type
1288 @code{&i/o-file-already-exists} is not raised
1289 and the file is truncated to zero length.
1291 If the file already exists, the exception with condition type
1292 @code{&i/o-file-already-exists} is not raised,
1293 even if @code{no-create} is not included,
1294 and the file is truncated to zero length.
1296 If the file already exists and the exception with condition type
1297 @code{&i/o-file-already-exists} has been inhibited by inclusion of
1298 @code{no-create} or @code{no-fail}, the file is not truncated, but
1299 the port's current position is still set to the beginning of the
1303 These options have no effect when a file is opened only for input.
1304 Symbols other than those listed above may be used as
1305 @var{file-options-symbol}s; they have implementation-specific meaning,
1309 Only the name of @var{file-options-symbol} is significant.
1313 @node R6RS Buffer Modes
1314 @subsubsection Buffer Modes
1316 Each port has an associated buffer mode. For an output port, the
1317 buffer mode defines when an output operation flushes the buffer
1318 associated with the output port. For an input port, the buffer mode
1319 defines how much data will be read to satisfy read operations. The
1320 possible buffer modes are the symbols @code{none} for no buffering,
1321 @code{line} for flushing upon line endings and reading up to line
1322 endings, or other implementation-dependent behavior,
1323 and @code{block} for arbitrary buffering. This section uses
1324 the parameter name @var{buffer-mode} for arguments that must be
1325 buffer-mode symbols.
1327 If two ports are connected to the same mutable source, both ports
1328 are unbuffered, and reading a byte or character from that shared
1329 source via one of the two ports would change the bytes or characters
1330 seen via the other port, a lookahead operation on one port will
1331 render the peeked byte or character inaccessible via the other port,
1332 while a subsequent read operation on the peeked port will see the
1333 peeked byte or character even though the port is otherwise unbuffered.
1335 In other words, the semantics of buffering is defined in terms of side
1336 effects on shared mutable sources, and a lookahead operation has the
1337 same side effect on the shared source as a read operation.
1339 @deffn {Scheme Syntax} buffer-mode @var{buffer-mode-symbol}
1341 @var{buffer-mode-symbol} must be a symbol whose name is one of
1342 @code{none}, @code{line}, and @code{block}. The result is the
1343 corresponding symbol, and specifies the associated buffer mode.
1346 Only the name of @var{buffer-mode-symbol} is significant.
1350 @deffn {Scheme Procedure} buffer-mode? obj
1351 Returns @code{#t} if the argument is a valid buffer-mode symbol, and
1352 returns @code{#f} otherwise.
1355 @node R6RS Transcoders
1356 @subsubsection Transcoders
1358 @cindex end-of-line style
1361 @cindex textual port
1363 Several different Unicode encoding schemes describe standard ways to
1364 encode characters and strings as byte sequences and to decode those
1365 sequences. Within this document, a @dfn{codec} is an immutable Scheme
1366 object that represents a Unicode or similar encoding scheme.
1368 An @dfn{end-of-line style} is a symbol that, if it is not @code{none},
1369 describes how a textual port transcodes representations of line endings.
1371 A @dfn{transcoder} is an immutable Scheme object that combines a codec
1372 with an end-of-line style and a method for handling decoding errors.
1373 Each transcoder represents some specific bidirectional (but not
1374 necessarily lossless), possibly stateful translation between byte
1375 sequences and Unicode characters and strings. Every transcoder can
1376 operate in the input direction (bytes to characters) or in the output
1377 direction (characters to bytes). A @var{transcoder} parameter name
1378 means that the corresponding argument must be a transcoder.
1380 A @dfn{binary port} is a port that supports binary I/O, does not have an
1381 associated transcoder and does not support textual I/O. A @dfn{textual
1382 port} is a port that supports textual I/O, and does not support binary
1383 I/O. A textual port may or may not have an associated transcoder.
1385 @deffn {Scheme Procedure} latin-1-codec
1386 @deffnx {Scheme Procedure} utf-8-codec
1387 @deffnx {Scheme Procedure} utf-16-codec
1389 These are predefined codecs for the ISO 8859-1, UTF-8, and UTF-16
1392 A call to any of these procedures returns a value that is equal in the
1393 sense of @code{eqv?} to the result of any other call to the same
1397 @deffn {Scheme Syntax} eol-style @var{eol-style-symbol}
1399 @var{eol-style-symbol} should be a symbol whose name is one of
1400 @code{lf}, @code{cr}, @code{crlf}, @code{nel}, @code{crnel}, @code{ls},
1403 The form evaluates to the corresponding symbol. If the name of
1404 @var{eol-style-symbol} is not one of these symbols, the effect and
1405 result are implementation-dependent; in particular, the result may be an
1406 eol-style symbol acceptable as an @var{eol-style} argument to
1407 @code{make-transcoder}. Otherwise, an exception is raised.
1409 All eol-style symbols except @code{none} describe a specific
1410 line-ending encoding:
1418 carriage return, linefeed
1422 carriage return, next line
1427 For a textual port with a transcoder, and whose transcoder has an
1428 eol-style symbol @code{none}, no conversion occurs. For a textual input
1429 port, any eol-style symbol other than @code{none} means that all of the
1430 above line-ending encodings are recognized and are translated into a
1431 single linefeed. For a textual output port, @code{none} and @code{lf}
1432 are equivalent. Linefeed characters are encoded according to the
1433 specified eol-style symbol, and all other characters that participate in
1434 possible line endings are encoded as is.
1437 Only the name of @var{eol-style-symbol} is significant.
1441 @deffn {Scheme Procedure} native-eol-style
1442 Returns the default end-of-line style of the underlying platform, e.g.,
1443 @code{lf} on Unix and @code{crlf} on Windows.
1446 @deffn {Condition Type} &i/o-decoding
1447 @deffnx {Scheme Procedure} make-i/o-decoding-error port
1448 @deffnx {Scheme Procedure} i/o-decoding-error? obj
1450 This condition type could be defined by
1453 (define-condition-type &i/o-decoding &i/o-port
1454 make-i/o-decoding-error i/o-decoding-error?)
1457 An exception with this type is raised when one of the operations for
1458 textual input from a port encounters a sequence of bytes that cannot be
1459 translated into a character or string by the input direction of the
1462 When such an exception is raised, the port's position is past the
1466 @deffn {Condition Type} &i/o-encoding
1467 @deffnx {Scheme Procedure} make-i/o-encoding-error port char
1468 @deffnx {Scheme Procedure} i/o-encoding-error? obj
1469 @deffnx {Scheme Procedure} i/o-encoding-error-char condition
1471 This condition type could be defined by
1474 (define-condition-type &i/o-encoding &i/o-port
1475 make-i/o-encoding-error i/o-encoding-error?
1476 (char i/o-encoding-error-char))
1479 An exception with this type is raised when one of the operations for
1480 textual output to a port encounters a character that cannot be
1481 translated into bytes by the output direction of the port's transcoder.
1482 @var{char} is the character that could not be encoded.
1485 @deffn {Scheme Syntax} error-handling-mode @var{error-handling-mode-symbol}
1487 @var{error-handling-mode-symbol} should be a symbol whose name is one of
1488 @code{ignore}, @code{raise}, and @code{replace}. The form evaluates to
1489 the corresponding symbol. If @var{error-handling-mode-symbol} is not
1490 one of these identifiers, effect and result are
1491 implementation-dependent: The result may be an error-handling-mode
1492 symbol acceptable as a @var{handling-mode} argument to
1493 @code{make-transcoder}. If it is not acceptable as a
1494 @var{handling-mode} argument to @code{make-transcoder}, an exception is
1498 Only the name of @var{error-handling-mode-symbol} is significant.
1501 The error-handling mode of a transcoder specifies the behavior
1502 of textual I/O operations in the presence of encoding or decoding
1505 If a textual input operation encounters an invalid or incomplete
1506 character encoding, and the error-handling mode is @code{ignore}, an
1507 appropriate number of bytes of the invalid encoding are ignored and
1508 decoding continues with the following bytes.
1510 If the error-handling mode is @code{replace}, the replacement
1511 character U+FFFD is injected into the data stream, an appropriate
1512 number of bytes are ignored, and decoding
1513 continues with the following bytes.
1515 If the error-handling mode is @code{raise}, an exception with condition
1516 type @code{&i/o-decoding} is raised.
1518 If a textual output operation encounters a character it cannot encode,
1519 and the error-handling mode is @code{ignore}, the character is ignored
1520 and encoding continues with the next character. If the error-handling
1521 mode is @code{replace}, a codec-specific replacement character is
1522 emitted by the transcoder, and encoding continues with the next
1523 character. The replacement character is U+FFFD for transcoders whose
1524 codec is one of the Unicode encodings, but is the @code{?} character
1525 for the Latin-1 encoding. If the error-handling mode is @code{raise},
1526 an exception with condition type @code{&i/o-encoding} is raised.
1529 @deffn {Scheme Procedure} make-transcoder codec
1530 @deffnx {Scheme Procedure} make-transcoder codec eol-style
1531 @deffnx {Scheme Procedure} make-transcoder codec eol-style handling-mode
1533 @var{codec} must be a codec; @var{eol-style}, if present, an eol-style
1534 symbol; and @var{handling-mode}, if present, an error-handling-mode
1537 @var{eol-style} may be omitted, in which case it defaults to the native
1538 end-of-line style of the underlying platform. @var{handling-mode} may
1539 be omitted, in which case it defaults to @code{replace}. The result is
1540 a transcoder with the behavior specified by its arguments.
1543 @deffn {Scheme procedure} native-transcoder
1544 Returns an implementation-dependent transcoder that represents a
1545 possibly locale-dependent ``native'' transcoding.
1548 @deffn {Scheme Procedure} transcoder-codec transcoder
1549 @deffnx {Scheme Procedure} transcoder-eol-style transcoder
1550 @deffnx {Scheme Procedure} transcoder-error-handling-mode transcoder
1552 These are accessors for transcoder objects; when applied to a
1553 transcoder returned by @code{make-transcoder}, they return the
1554 @var{codec}, @var{eol-style}, and @var{handling-mode} arguments,
1558 @deffn {Scheme Procedure} bytevector->string bytevector transcoder
1560 Returns the string that results from transcoding the
1561 @var{bytevector} according to the input direction of the transcoder.
1564 @deffn {Scheme Procedure} string->bytevector string transcoder
1566 Returns the bytevector that results from transcoding the
1567 @var{string} according to the output direction of the transcoder.
1570 @node R6RS End-of-File
1571 @subsubsection The End-of-File Object
1576 R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io
1579 @deffn {Scheme Procedure} eof-object? obj
1580 @deffnx {C Function} scm_eof_object_p (obj)
1581 Return true if @var{obj} is the end-of-file (EOF) object.
1584 In addition, the following procedure is provided:
1586 @deffn {Scheme Procedure} eof-object
1587 @deffnx {C Function} scm_eof_object ()
1588 Return the end-of-file (EOF) object.
1591 (eof-object? (eof-object))
1597 @node R6RS Port Manipulation
1598 @subsubsection Port Manipulation
1600 The procedures listed below operate on any kind of R6RS I/O port.
1602 @deffn {Scheme Procedure} port? obj
1603 Returns @code{#t} if the argument is a port, and returns @code{#f}
1607 @deffn {Scheme Procedure} port-transcoder port
1608 Returns the transcoder associated with @var{port} if @var{port} is
1609 textual and has an associated transcoder, and returns @code{#f} if
1610 @var{port} is binary or does not have an associated transcoder.
1613 @deffn {Scheme Procedure} binary-port? port
1614 Return @code{#t} if @var{port} is a @dfn{binary port}, suitable for
1615 binary data input/output.
1617 Note that internally Guile does not differentiate between binary and
1618 textual ports, unlike the R6RS. Thus, this procedure returns true when
1619 @var{port} does not have an associated encoding---i.e., when
1620 @code{(port-encoding @var{port})} is @code{#f} (@pxref{Ports,
1621 port-encoding}). This is the case for ports returned by R6RS procedures
1622 such as @code{open-bytevector-input-port} and
1623 @code{make-custom-binary-output-port}.
1625 However, Guile currently does not prevent use of textual I/O procedures
1626 such as @code{display} or @code{read-char} with binary ports. Doing so
1627 ``upgrades'' the port from binary to textual, under the ISO-8859-1
1628 encoding. Likewise, Guile does not prevent use of
1629 @code{set-port-encoding!} on a binary port, which also turns it into a
1633 @deffn {Scheme Procedure} textual-port? port
1634 Always return @code{#t}, as all ports can be used for textual I/O in
1638 @deffn {Scheme Procedure} transcoded-port binary-port transcoder
1639 The @code{transcoded-port} procedure
1640 returns a new textual port with the specified @var{transcoder}.
1641 Otherwise the new textual port's state is largely the same as
1642 that of @var{binary-port}.
1643 If @var{binary-port} is an input port, the new textual
1644 port will be an input port and
1645 will transcode the bytes that have not yet been read from
1647 If @var{binary-port} is an output port, the new textual
1648 port will be an output port and
1649 will transcode output characters into bytes that are
1650 written to the byte sink represented by @var{binary-port}.
1652 As a side effect, however, @code{transcoded-port}
1653 closes @var{binary-port} in
1654 a special way that allows the new textual port to continue to
1655 use the byte source or sink represented by @var{binary-port},
1656 even though @var{binary-port} itself is closed and cannot
1657 be used by the input and output operations described in this
1661 @deffn {Scheme Procedure} port-position port
1662 If @var{port} supports it (see below), return the offset (an integer)
1663 indicating where the next octet will be read from/written to in
1664 @var{port}. If @var{port} does not support this operation, an error
1665 condition is raised.
1667 This is similar to Guile's @code{seek} procedure with the
1668 @code{SEEK_CUR} argument (@pxref{Random Access}).
1671 @deffn {Scheme Procedure} port-has-port-position? port
1672 Return @code{#t} is @var{port} supports @code{port-position}.
1675 @deffn {Scheme Procedure} set-port-position! port offset
1676 If @var{port} supports it (see below), set the position where the next
1677 octet will be read from/written to @var{port} to @var{offset} (an
1678 integer). If @var{port} does not support this operation, an error
1679 condition is raised.
1681 This is similar to Guile's @code{seek} procedure with the
1682 @code{SEEK_SET} argument (@pxref{Random Access}).
1685 @deffn {Scheme Procedure} port-has-set-port-position!? port
1686 Return @code{#t} is @var{port} supports @code{set-port-position!}.
1689 @deffn {Scheme Procedure} call-with-port port proc
1690 Call @var{proc}, passing it @var{port} and closing @var{port} upon exit
1691 of @var{proc}. Return the return values of @var{proc}.
1694 @node R6RS Input Ports
1695 @subsubsection Input Ports
1697 @deffn {Scheme Procedure} input-port? obj
1698 Returns @code{#t} if the argument is an input port (or a combined input
1699 and output port), and returns @code{#f} otherwise.
1702 @deffn {Scheme Procedure} port-eof? input-port
1704 if the @code{lookahead-u8} procedure (if @var{input-port} is a binary port)
1705 or the @code{lookahead-char} procedure (if @var{input-port} is a textual port)
1707 the end-of-file object, and @code{#f} otherwise.
1708 The operation may block indefinitely if no data is available
1709 but the port cannot be determined to be at end of file.
1712 @deffn {Scheme Procedure} open-file-input-port filename
1713 @deffnx {Scheme Procedure} open-file-input-port filename file-options
1714 @deffnx {Scheme Procedure} open-file-input-port filename file-options buffer-mode
1715 @deffnx {Scheme Procedure} open-file-input-port filename file-options buffer-mode maybe-transcoder
1716 @var{maybe-transcoder} must be either a transcoder or @code{#f}.
1718 The @code{open-file-input-port} procedure returns an
1719 input port for the named file. The @var{file-options} and
1720 @var{maybe-transcoder} arguments are optional.
1722 The @var{file-options} argument, which may determine
1723 various aspects of the returned port (@pxref{R6RS File Options}),
1724 defaults to the value of @code{(file-options)}.
1726 The @var{buffer-mode} argument, if supplied,
1727 must be one of the symbols that name a buffer mode.
1728 The @var{buffer-mode} argument defaults to @code{block}.
1730 If @var{maybe-transcoder} is a transcoder, it becomes the transcoder associated
1731 with the returned port.
1733 If @var{maybe-transcoder} is @code{#f} or absent,
1734 the port will be a binary port and will support the
1735 @code{port-position} and @code{set-port-position!} operations.
1736 Otherwise the port will be a textual port, and whether it supports
1737 the @code{port-position} and @code{set-port-position!} operations
1738 is implementation-dependent (and possibly transcoder-dependent).
1741 @deffn {Scheme Procedure} standard-input-port
1742 Returns a fresh binary input port connected to standard input. Whether
1743 the port supports the @code{port-position} and @code{set-port-position!}
1744 operations is implementation-dependent.
1747 @deffn {Scheme Procedure} current-input-port
1748 This returns a default textual port for input. Normally, this default
1749 port is associated with standard input, but can be dynamically
1750 re-assigned using the @code{with-input-from-file} procedure from the
1751 @code{io simple (6)} library (@pxref{rnrs io simple}). The port may or
1752 may not have an associated transcoder; if it does, the transcoder is
1753 implementation-dependent.
1756 @node R6RS Binary Input
1757 @subsubsection Binary Input
1759 @cindex binary input
1761 R6RS binary input ports can be created with the procedures described
1764 @deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder]
1765 @deffnx {C Function} scm_open_bytevector_input_port (bv, transcoder)
1766 Return an input port whose contents are drawn from bytevector @var{bv}
1767 (@pxref{Bytevectors}).
1769 @c FIXME: Update description when implemented.
1770 The @var{transcoder} argument is currently not supported.
1773 @cindex custom binary input ports
1775 @deffn {Scheme Procedure} make-custom-binary-input-port id read! get-position set-position! close
1776 @deffnx {C Function} scm_make_custom_binary_input_port (id, read!, get-position, set-position!, close)
1777 Return a new custom binary input port@footnote{This is similar in spirit
1778 to Guile's @dfn{soft ports} (@pxref{Soft Ports}).} named @var{id} (a
1779 string) whose input is drained by invoking @var{read!} and passing it a
1780 bytevector, an index where bytes should be written, and the number of
1781 bytes to read. The @code{read!} procedure must return an integer
1782 indicating the number of bytes read, or @code{0} to indicate the
1785 Optionally, if @var{get-position} is not @code{#f}, it must be a thunk
1786 that will be called when @code{port-position} is invoked on the custom
1787 binary port and should return an integer indicating the position within
1788 the underlying data stream; if @var{get-position} was not supplied, the
1789 returned port does not support @code{port-position}.
1791 Likewise, if @var{set-position!} is not @code{#f}, it should be a
1792 one-argument procedure. When @code{set-port-position!} is invoked on the
1793 custom binary input port, @var{set-position!} is passed an integer
1794 indicating the position of the next byte is to read.
1796 Finally, if @var{close} is not @code{#f}, it must be a thunk. It is
1797 invoked when the custom binary input port is closed.
1799 The returned port is fully buffered by default, but its buffering mode
1800 can be changed using @code{setvbuf} (@pxref{Ports and File Descriptors,
1803 Using a custom binary input port, the @code{open-bytevector-input-port}
1804 procedure could be implemented as follows:
1807 (define (open-bytevector-input-port source)
1809 (define length (bytevector-length source))
1811 (define (read! bv start count)
1812 (let ((count (min count (- length position))))
1813 (bytevector-copy! source position
1815 (set! position (+ position count))
1818 (define (get-position) position)
1820 (define (set-position! new-position)
1821 (set! position new-position))
1823 (make-custom-binary-input-port "the port" read!
1827 (read (open-bytevector-input-port (string->utf8 "hello")))
1832 @cindex binary input
1833 Binary input is achieved using the procedures below:
1835 @deffn {Scheme Procedure} get-u8 port
1836 @deffnx {C Function} scm_get_u8 (port)
1837 Return an octet read from @var{port}, a binary input port, blocking as
1838 necessary, or the end-of-file object.
1841 @deffn {Scheme Procedure} lookahead-u8 port
1842 @deffnx {C Function} scm_lookahead_u8 (port)
1843 Like @code{get-u8} but does not update @var{port}'s position to point
1847 @deffn {Scheme Procedure} get-bytevector-n port count
1848 @deffnx {C Function} scm_get_bytevector_n (port, count)
1849 Read @var{count} octets from @var{port}, blocking as necessary and
1850 return a bytevector containing the octets read. If fewer bytes are
1851 available, a bytevector smaller than @var{count} is returned.
1854 @deffn {Scheme Procedure} get-bytevector-n! port bv start count
1855 @deffnx {C Function} scm_get_bytevector_n_x (port, bv, start, count)
1856 Read @var{count} bytes from @var{port} and store them in @var{bv}
1857 starting at index @var{start}. Return either the number of bytes
1858 actually read or the end-of-file object.
1861 @deffn {Scheme Procedure} get-bytevector-some port
1862 @deffnx {C Function} scm_get_bytevector_some (port)
1863 Read from @var{port}, blocking as necessary, until bytes are available
1864 or an end-of-file is reached. Return either the end-of-file object or a
1865 new bytevector containing some of the available bytes (at least one),
1866 and update the port position to point just past these bytes.
1869 @deffn {Scheme Procedure} get-bytevector-all port
1870 @deffnx {C Function} scm_get_bytevector_all (port)
1871 Read from @var{port}, blocking as necessary, until the end-of-file is
1872 reached. Return either a new bytevector containing the data read or the
1873 end-of-file object (if no data were available).
1876 The @code{(ice-9 binary-ports)} module provides the following procedure
1877 as an extension to @code{(rnrs io ports)}:
1879 @deffn {Scheme Procedure} unget-bytevector port bv [start [count]]
1880 @deffnx {C Function} scm_unget_bytevector (port, bv, start, count)
1881 Place the contents of @var{bv} in @var{port}, optionally starting at
1882 index @var{start} and limiting to @var{count} octets, so that its bytes
1883 will be read from left-to-right as the next bytes from @var{port} during
1884 subsequent read operations. If called multiple times, the unread bytes
1885 will be read again in last-in first-out order.
1888 @node R6RS Textual Input
1889 @subsubsection Textual Input
1891 @deffn {Scheme Procedure} get-char textual-input-port
1892 Reads from @var{textual-input-port}, blocking as necessary, until a
1893 complete character is available from @var{textual-input-port},
1894 or until an end of file is reached.
1896 If a complete character is available before the next end of file,
1897 @code{get-char} returns that character and updates the input port to
1898 point past the character. If an end of file is reached before any
1899 character is read, @code{get-char} returns the end-of-file object.
1902 @deffn {Scheme Procedure} lookahead-char textual-input-port
1903 The @code{lookahead-char} procedure is like @code{get-char}, but it does
1904 not update @var{textual-input-port} to point past the character.
1907 @deffn {Scheme Procedure} get-string-n textual-input-port count
1909 @var{count} must be an exact, non-negative integer object, representing
1910 the number of characters to be read.
1912 The @code{get-string-n} procedure reads from @var{textual-input-port},
1913 blocking as necessary, until @var{count} characters are available, or
1914 until an end of file is reached.
1916 If @var{count} characters are available before end of file,
1917 @code{get-string-n} returns a string consisting of those @var{count}
1918 characters. If fewer characters are available before an end of file, but
1919 one or more characters can be read, @code{get-string-n} returns a string
1920 containing those characters. In either case, the input port is updated
1921 to point just past the characters read. If no characters can be read
1922 before an end of file, the end-of-file object is returned.
1925 @deffn {Scheme Procedure} get-string-n! textual-input-port string start count
1927 @var{start} and @var{count} must be exact, non-negative integer objects,
1928 with @var{count} representing the number of characters to be read.
1929 @var{string} must be a string with at least $@var{start} + @var{count}$
1932 The @code{get-string-n!} procedure reads from @var{textual-input-port}
1933 in the same manner as @code{get-string-n}. If @var{count} characters
1934 are available before an end of file, they are written into @var{string}
1935 starting at index @var{start}, and @var{count} is returned. If fewer
1936 characters are available before an end of file, but one or more can be
1937 read, those characters are written into @var{string} starting at index
1938 @var{start} and the number of characters actually read is returned as an
1939 exact integer object. If no characters can be read before an end of
1940 file, the end-of-file object is returned.
1943 @deffn {Scheme Procedure} get-string-all textual-input-port
1944 Reads from @var{textual-input-port} until an end of file, decoding
1945 characters in the same manner as @code{get-string-n} and
1946 @code{get-string-n!}.
1948 If characters are available before the end of file, a string containing
1949 all the characters decoded from that data are returned. If no character
1950 precedes the end of file, the end-of-file object is returned.
1953 @deffn {Scheme Procedure} get-line textual-input-port
1954 Reads from @var{textual-input-port} up to and including the linefeed
1955 character or end of file, decoding characters in the same manner as
1956 @code{get-string-n} and @code{get-string-n!}.
1958 If a linefeed character is read, a string containing all of the text up
1959 to (but not including) the linefeed character is returned, and the port
1960 is updated to point just past the linefeed character. If an end of file
1961 is encountered before any linefeed character is read, but some
1962 characters have been read and decoded as characters, a string containing
1963 those characters is returned. If an end of file is encountered before
1964 any characters are read, the end-of-file object is returned.
1967 The end-of-line style, if not @code{none}, will cause all line endings
1968 to be read as linefeed characters. @xref{R6RS Transcoders}.
1972 @deffn {Scheme Procedure} get-datum textual-input-port count
1973 Reads an external representation from @var{textual-input-port} and returns the
1974 datum it represents. The @code{get-datum} procedure returns the next
1975 datum that can be parsed from the given @var{textual-input-port}, updating
1976 @var{textual-input-port} to point exactly past the end of the external
1977 representation of the object.
1979 Any @emph{interlexeme space} (comment or whitespace, @pxref{Scheme
1980 Syntax}) in the input is first skipped. If an end of file occurs after
1981 the interlexeme space, the end-of-file object (@pxref{R6RS End-of-File})
1984 If a character inconsistent with an external representation is
1985 encountered in the input, an exception with condition types
1986 @code{&lexical} and @code{&i/o-read} is raised. Also, if the end of
1987 file is encountered after the beginning of an external representation,
1988 but the external representation is incomplete and therefore cannot be
1989 parsed, an exception with condition types @code{&lexical} and
1990 @code{&i/o-read} is raised.
1993 @node R6RS Output Ports
1994 @subsubsection Output Ports
1996 @deffn {Scheme Procedure} output-port? obj
1997 Returns @code{#t} if the argument is an output port (or a
1998 combined input and output port), @code{#f} otherwise.
2001 @deffn {Scheme Procedure} flush-output-port port
2002 Flushes any buffered output from the buffer of @var{output-port} to the
2003 underlying file, device, or object. The @code{flush-output-port}
2004 procedure returns an unspecified values.
2007 @deffn {Scheme Procedure} open-file-output-port filename
2008 @deffnx {Scheme Procedure} open-file-output-port filename file-options
2009 @deffnx {Scheme Procedure} open-file-output-port filename file-options buffer-mode
2010 @deffnx {Scheme Procedure} open-file-output-port filename file-options buffer-mode maybe-transcoder
2012 @var{maybe-transcoder} must be either a transcoder or @code{#f}.
2014 The @code{open-file-output-port} procedure returns an output port for the named file.
2016 The @var{file-options} argument, which may determine various aspects of
2017 the returned port (@pxref{R6RS File Options}), defaults to the value of
2018 @code{(file-options)}.
2020 The @var{buffer-mode} argument, if supplied,
2021 must be one of the symbols that name a buffer mode.
2022 The @var{buffer-mode} argument defaults to @code{block}.
2024 If @var{maybe-transcoder} is a transcoder, it becomes the transcoder
2025 associated with the port.
2027 If @var{maybe-transcoder} is @code{#f} or absent,
2028 the port will be a binary port and will support the
2029 @code{port-position} and @code{set-port-position!} operations.
2030 Otherwise the port will be a textual port, and whether it supports
2031 the @code{port-position} and @code{set-port-position!} operations
2032 is implementation-dependent (and possibly transcoder-dependent).
2035 @deffn {Scheme Procedure} standard-output-port
2036 @deffnx {Scheme Procedure} standard-error-port
2037 Returns a fresh binary output port connected to the standard output or
2038 standard error respectively. Whether the port supports the
2039 @code{port-position} and @code{set-port-position!} operations is
2040 implementation-dependent.
2043 @deffn {Scheme Procedure} current-output-port
2044 @deffnx {Scheme Procedure} current-error-port
2045 These return default textual ports for regular output and error output.
2046 Normally, these default ports are associated with standard output, and
2047 standard error, respectively. The return value of
2048 @code{current-output-port} can be dynamically re-assigned using the
2049 @code{with-output-to-file} procedure from the @code{io simple (6)}
2050 library (@pxref{rnrs io simple}). A port returned by one of these
2051 procedures may or may not have an associated transcoder; if it does, the
2052 transcoder is implementation-dependent.
2055 @node R6RS Binary Output
2056 @subsubsection Binary Output
2058 Binary output ports can be created with the procedures below.
2060 @deffn {Scheme Procedure} open-bytevector-output-port [transcoder]
2061 @deffnx {C Function} scm_open_bytevector_output_port (transcoder)
2062 Return two values: a binary output port and a procedure. The latter
2063 should be called with zero arguments to obtain a bytevector containing
2064 the data accumulated by the port, as illustrated below.
2069 (open-bytevector-output-port))
2070 (lambda (port get-bytevector)
2071 (display "hello" port)
2074 @result{} #vu8(104 101 108 108 111)
2077 @c FIXME: Update description when implemented.
2078 The @var{transcoder} argument is currently not supported.
2081 @cindex custom binary output ports
2083 @deffn {Scheme Procedure} make-custom-binary-output-port id write! get-position set-position! close
2084 @deffnx {C Function} scm_make_custom_binary_output_port (id, write!, get-position, set-position!, close)
2085 Return a new custom binary output port named @var{id} (a string) whose
2086 output is sunk by invoking @var{write!} and passing it a bytevector, an
2087 index where bytes should be read from this bytevector, and the number of
2088 bytes to be ``written''. The @code{write!} procedure must return an
2089 integer indicating the number of bytes actually written; when it is
2090 passed @code{0} as the number of bytes to write, it should behave as
2091 though an end-of-file was sent to the byte sink.
2093 The other arguments are as for @code{make-custom-binary-input-port}
2094 (@pxref{R6RS Binary Input, @code{make-custom-binary-input-port}}).
2097 @cindex binary output
2098 Writing to a binary output port can be done using the following
2101 @deffn {Scheme Procedure} put-u8 port octet
2102 @deffnx {C Function} scm_put_u8 (port, octet)
2103 Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
2107 @deffn {Scheme Procedure} put-bytevector port bv [start [count]]
2108 @deffnx {C Function} scm_put_bytevector (port, bv, start, count)
2109 Write the contents of @var{bv} to @var{port}, optionally starting at
2110 index @var{start} and limiting to @var{count} octets.
2113 @node R6RS Textual Output
2114 @subsubsection Textual Output
2116 @deffn {Scheme Procedure} put-char port char
2117 Writes @var{char} to the port. The @code{put-char} procedure returns
2118 an unspecified value.
2121 @deffn {Scheme Procedure} put-string port string
2122 @deffnx {Scheme Procedure} put-string port string start
2123 @deffnx {Scheme Procedure} put-string port string start count
2125 @var{start} and @var{count} must be non-negative exact integer objects.
2126 @var{string} must have a length of at least @math{@var{start} +
2127 @var{count}}. @var{start} defaults to 0. @var{count} defaults to
2128 @math{@code{(string-length @var{string})} - @var{start}}$. The
2129 @code{put-string} procedure writes the @var{count} characters of
2130 @var{string} starting at index @var{start} to the port. The
2131 @code{put-string} procedure returns an unspecified value.
2134 @deffn {Scheme Procedure} put-datum textual-output-port datum
2135 @var{datum} should be a datum value. The @code{put-datum} procedure
2136 writes an external representation of @var{datum} to
2137 @var{textual-output-port}. The specific external representation is
2138 implementation-dependent. However, whenever possible, an implementation
2139 should produce a representation for which @code{get-datum}, when reading
2140 the representation, will return an object equal (in the sense of
2141 @code{equal?}) to @var{datum}.
2144 Not all datums may allow producing an external representation for which
2145 @code{get-datum} will produce an object that is equal to the
2146 original. Specifically, NaNs contained in @var{datum} may make
2151 The @code{put-datum} procedure merely writes the external
2152 representation, but no trailing delimiter. If @code{put-datum} is
2153 used to write several subsequent external representations to an
2154 output port, care should be taken to delimit them properly so they can
2155 be read back in by subsequent calls to @code{get-datum}.
2159 @node I/O Extensions
2160 @subsection Using and Extending Ports in C
2163 * C Port Interface:: Using ports from C.
2164 * Port Implementation:: How to implement a new port type in C.
2168 @node C Port Interface
2169 @subsubsection C Port Interface
2170 @cindex C port interface
2171 @cindex Port, C interface
2173 This section describes how to use Scheme ports from C.
2175 @subsubheading Port basics
2178 @tindex scm_ptob_descriptor
2180 @findex SCM_PTAB_ENTRY
2183 There are two main data structures. A port type object (ptob) is of
2184 type @code{scm_ptob_descriptor}. A port instance is of type
2185 @code{scm_port}. Given an @code{SCM} variable which points to a port,
2186 the corresponding C port object can be obtained using the
2187 @code{SCM_PTAB_ENTRY} macro. The ptob can be obtained by using
2188 @code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs}
2191 @subsubheading Port buffers
2193 An input port always has a read buffer and an output port always has a
2194 write buffer. However the size of these buffers is not guaranteed to be
2195 more than one byte (e.g., the @code{shortbuf} field in @code{scm_port}
2196 which is used when no other buffer is allocated). The way in which the
2197 buffers are allocated depends on the implementation of the ptob. For
2198 example in the case of an fport, buffers may be allocated with malloc
2199 when the port is created, but in the case of an strport the underlying
2200 string is used as the buffer.
2202 @subsubheading The @code{rw_random} flag
2204 Special treatment is required for ports which can be seeked at random.
2205 Before various operations, such as seeking the port or changing from
2206 input to output on a bidirectional port or vice versa, the port
2207 implementation must be given a chance to update its state. The write
2208 buffer is updated by calling the @code{flush} ptob procedure and the
2209 input buffer is updated by calling the @code{end_input} ptob procedure.
2210 In the case of an fport, @code{flush} causes buffered output to be
2211 written to the file descriptor, while @code{end_input} causes the
2212 descriptor position to be adjusted to account for buffered input which
2215 The special treatment must be performed if the @code{rw_random} flag in
2216 the port is non-zero.
2218 @subsubheading The @code{rw_active} variable
2220 The @code{rw_active} variable in the port is only used if
2221 @code{rw_random} is set. It's defined as an enum with the following
2226 the read buffer may have unread data.
2228 @item SCM_PORT_WRITE
2229 the write buffer may have unwritten data.
2231 @item SCM_PORT_NEITHER
2232 neither the write nor the read buffer has data.
2235 @subsubheading Reading from a port.
2237 To read from a port, it's possible to either call existing libguile
2238 procedures such as @code{scm_getc} and @code{scm_read_line} or to read
2239 data from the read buffer directly. Reading from the buffer involves
2240 the following steps:
2244 Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}.
2247 Fill the read buffer, if it's empty, using @code{scm_fill_input}.
2249 @item Read the data from the buffer and update the read position in
2250 the buffer. Steps 2) and 3) may be repeated as many times as required.
2252 @item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set.
2254 @item update the port's line and column counts.
2257 @subsubheading Writing to a port.
2259 To write data to a port, calling @code{scm_lfwrite} should be sufficient for
2260 most purposes. This takes care of the following steps:
2264 End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}.
2267 Pass the data to the ptob implementation using the @code{write} ptob
2268 procedure. The advantage of using the ptob @code{write} instead of
2269 manipulating the write buffer directly is that it allows the data to be
2270 written in one operation even if the port is using the single-byte
2274 Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random}
2279 @node Port Implementation
2280 @subsubsection Port Implementation
2281 @cindex Port implementation
2283 This section describes how to implement a new port type in C.
2285 As described in the previous section, a port type object (ptob) is
2286 a structure of type @code{scm_ptob_descriptor}. A ptob is created by
2287 calling @code{scm_make_port_type}.
2289 @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))
2290 Return a new port type object. The @var{name}, @var{fill_input} and
2291 @var{write} parameters are initial values for those port type fields,
2292 as described below. The other fields are initialized with default
2293 values and can be changed later.
2296 All of the elements of the ptob, apart from @code{name}, are procedures
2297 which collectively implement the port behaviour. Creating a new port
2298 type mostly involves writing these procedures.
2302 A pointer to a NUL terminated string: the name of the port type. This
2303 is the only element of @code{scm_ptob_descriptor} which is not
2304 a procedure. Set via the first argument to @code{scm_make_port_type}.
2307 Called during garbage collection to mark any SCM objects that a port
2308 object may contain. It doesn't need to be set unless the port has
2309 @code{SCM} components. Set using
2311 @deftypefun void scm_set_port_mark (scm_t_bits tc, SCM (*mark) (SCM port))
2315 Called when the port is collected during gc. It
2316 should free any resources used by the port.
2319 @deftypefun void scm_set_port_free (scm_t_bits tc, size_t (*free) (SCM port))
2323 Called when @code{write} is called on the port object, to print a
2324 port description. E.g., for an fport it may produce something like:
2325 @code{#<input: /etc/passwd 3>}. Set using
2327 @deftypefun void scm_set_port_print (scm_t_bits tc, int (*print) (SCM port, SCM dest_port, scm_print_state *pstate))
2328 The first argument @var{port} is the object being printed, the second
2329 argument @var{dest_port} is where its description should go.
2333 Not used at present. Set using
2335 @deftypefun void scm_set_port_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM))
2339 Called when the port is closed, unless it was collected during gc. It
2340 should free any resources used by the port.
2343 @deftypefun void scm_set_port_close (scm_t_bits tc, int (*close) (SCM port))
2347 Accept data which is to be written using the port. The port implementation
2348 may choose to buffer the data instead of processing it directly.
2349 Set via the third argument to @code{scm_make_port_type}.
2352 Complete the processing of buffered output data. Reset the value of
2353 @code{rw_active} to @code{SCM_PORT_NEITHER}.
2356 @deftypefun void scm_set_port_flush (scm_t_bits tc, void (*flush) (SCM port))
2360 Perform any synchronization required when switching from input to output
2361 on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}.
2364 @deftypefun void scm_set_port_end_input (scm_t_bits tc, void (*end_input) (SCM port, int offset))
2368 Read new data into the read buffer and return the first character. It
2369 can be assumed that the read buffer is empty when this procedure is called.
2370 Set via the second argument to @code{scm_make_port_type}.
2373 Return a lower bound on the number of bytes that could be read from the
2374 port without blocking. It can be assumed that the current state of
2375 @code{rw_active} is @code{SCM_PORT_NEITHER}.
2378 @deftypefun void scm_set_port_input_waiting (scm_t_bits tc, int (*input_waiting) (SCM port))
2382 Set the current position of the port. The procedure can not make
2383 any assumptions about the value of @code{rw_active} when it's
2384 called. It can reset the buffers first if desired by using something
2388 if (pt->rw_active == SCM_PORT_READ)
2389 scm_end_input (port);
2390 else if (pt->rw_active == SCM_PORT_WRITE)
2394 However note that this will have the side effect of discarding any data
2395 in the unread-char buffer, in addition to any side effects from the
2396 @code{end_input} and @code{flush} ptob procedures. This is undesirable
2397 when seek is called to measure the current position of the port, i.e.,
2398 @code{(seek p 0 SEEK_CUR)}. The libguile fport and string port
2399 implementations take care to avoid this problem.
2401 The procedure is set using
2403 @deftypefun void scm_set_port_seek (scm_t_bits tc, scm_t_off (*seek) (SCM port, scm_t_off offset, int whence))
2407 Truncate the port data to be specified length. It can be assumed that the
2408 current state of @code{rw_active} is @code{SCM_PORT_NEITHER}.
2411 @deftypefun void scm_set_port_truncate (scm_t_bits tc, void (*truncate) (SCM port, scm_t_off length))
2417 @subsection Handling of Unicode byte order marks.
2419 @cindex byte order mark
2421 This section documents the finer points of Guile's handling of Unicode
2422 byte order marks (BOMs). A byte order mark (U+FEFF) is typically found
2423 at the start of a UTF-16 or UTF-32 stream, to allow readers to reliably
2424 determine the byte order. Occasionally, a BOM is found at the start of
2425 a UTF-8 stream, but this is much less common and not generally
2428 Guile attempts to handle BOMs automatically, and in accordance with the
2429 recommendations of the Unicode Standard, when the port encoding is set
2430 to @code{UTF-8}, @code{UTF-16}, or @code{UTF-32}. In brief, Guile
2431 automatically writes a BOM at the start of a UTF-16 or UTF-32 stream,
2432 and automatically consumes one from the start of a UTF-8, UTF-16, or
2435 As specified in the Unicode Standard, a BOM is only handled specially at
2436 the start of a stream, and only if the port encoding is set to
2437 @code{UTF-8}, @code{UTF-16} or @code{UTF-32}. If the port encoding is
2438 set to @code{UTF-16BE}, @code{UTF-16LE}, @code{UTF-32BE}, or
2439 @code{UTF-32LE}, then BOMs are @emph{not} handled specially, and none of
2440 the special handling described in this section applies.
2444 To ensure that Guile will properly detect the byte order of a UTF-16 or
2445 UTF-32 stream, you must perform a textual read before any writes, seeks,
2446 or binary I/O. Guile will not attempt to read a BOM unless a read is
2447 explicitly requested at the start of the stream.
2450 If a textual write is performed before the first read, then an arbitrary
2451 byte order will be chosen. Currently, big endian is the default on all
2452 platforms, but that may change in the future. If you wish to explicitly
2453 control the byte order of an output stream, set the port encoding to
2454 @code{UTF-16BE}, @code{UTF-16LE}, @code{UTF-32BE}, or @code{UTF-32LE},
2455 and explicitly write a BOM (@code{#\xFEFF}) if desired.
2458 If @code{set-port-encoding!} is called in the middle of a stream, Guile
2459 treats this as a new logical ``start of stream'' for purposes of BOM
2460 handling, and will forget about any BOMs that had previously been seen.
2461 Therefore, it may choose a different byte order than had been used
2462 previously. This is intended to support multiple logical text streams
2463 embedded within a larger binary stream.
2466 Binary I/O operations are not guaranteed to update Guile's notion of
2467 whether the port is at the ``start of the stream'', nor are they
2468 guaranteed to produce or consume BOMs.
2471 For ports that support seeking (e.g. normal files), the input and output
2472 streams are considered linked: if the user reads first, then a BOM will
2473 be consumed (if appropriate), but later writes will @emph{not} produce a
2474 BOM. Similarly, if the user writes first, then later reads will
2475 @emph{not} consume a BOM.
2478 For ports that do not support seeking (e.g. pipes, sockets, and
2479 terminals), the input and output streams are considered
2480 @emph{independent} for purposes of BOM handling: the first read will
2481 consume a BOM (if appropriate), and the first write will @emph{also}
2482 produce a BOM (if appropriate). However, the input and output streams
2483 will always use the same byte order.
2486 Seeks to the beginning of a file will set the ``start of stream'' flags.
2487 Therefore, a subsequent textual read or write will consume or produce a
2488 BOM. However, unlike @code{set-port-encoding!}, if a byte order had
2489 already been chosen for the port, it will remain in effect after a seek,
2490 and cannot be changed by the presence of a BOM. Seeks anywhere other
2491 than the beginning of a file clear the ``start of stream'' flags.
2495 @c TeX-master: "guile.texi"