2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009, 2010
4 @c 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.
29 Sequential input/output in Scheme is represented by operations on a
30 @dfn{port}. This chapter explains the operations that Guile provides
31 for working with ports.
33 Ports are created by opening, for instance @code{open-file} for a file
34 (@pxref{File Ports}). Characters can be read from an input port and
35 written to an output port, or both on an input/output port. A port
36 can be closed (@pxref{Closing}) when no longer required, after which
37 any attempt to read or write is an error.
39 The formal definition of a port is very generic: an input port is
40 simply ``an object which can deliver characters on demand,'' and an
41 output port is ``an object which can accept characters.'' Because
42 this definition is so loose, it is easy to write functions that
43 simulate ports in software. @dfn{Soft ports} and @dfn{string ports}
44 are two interesting and powerful examples of this technique.
45 (@pxref{Soft Ports}, and @ref{String Ports}.)
47 Ports are garbage collected in the usual way (@pxref{Memory
48 Management}), and will be closed at that time if not already closed.
49 In this case any errors occurring in the close will not be reported.
50 Usually a program will want to explicitly close so as to be sure all
51 its operations have been successful. Of course if a program has
52 abandoned something due to an error or other condition then closing
53 problems are probably not of interest.
55 It is strongly recommended that file ports be closed explicitly when
56 no longer required. Most systems have limits on how many files can be
57 open, both on a per-process and a system-wide basis. A program that
58 uses many files should take care not to hit those limits. The same
59 applies to similar system resources such as pipes and sockets.
61 Note that automatic garbage collection is triggered only by memory
62 consumption, not by file or other resource usage, so a program cannot
63 rely on that to keep it away from system limits. An explicit call to
64 @code{gc} can of course be relied on to pick up unreferenced ports.
65 If program flow makes it hard to be certain when to close then this
66 may be an acceptable way to control resource usage.
68 All file access uses the ``LFS'' large file support functions when
69 available, so files bigger than 2 Gbytes (@math{2^31} bytes) can be
70 read and written on a 32-bit system.
72 Each port has an associated character encoding that controls how bytes
73 read from the port are converted to characters and string and controls
74 how characters and strings written to the port are converted to bytes.
75 When ports are created, they inherit their character encoding from the
76 current locale, but, that can be modified after the port is created.
78 Currently, the ports only work with @emph{non-modal} encodings. Most
79 encodings are non-modal, meaning that the conversion of bytes to a
80 string doesn't depend on its context: the same byte sequence will always
81 return the same string. A couple of modal encodings are in common use,
82 like ISO-2022-JP and ISO-2022-KR, and they are not yet supported.
84 Each port also has an associated conversion strategy: what to do when
85 a Guile character can't be converted to the port's encoded character
86 representation for output. There are three possible strategies: to
87 raise an error, to replace the character with a hex escape, or to
88 replace the character with a substitute character.
91 @deffn {Scheme Procedure} input-port? x
92 @deffnx {C Function} scm_input_port_p (x)
93 Return @code{#t} if @var{x} is an input port, otherwise return
94 @code{#f}. Any object satisfying this predicate also satisfies
99 @deffn {Scheme Procedure} output-port? x
100 @deffnx {C Function} scm_output_port_p (x)
101 Return @code{#t} if @var{x} is an output port, otherwise return
102 @code{#f}. Any object satisfying this predicate also satisfies
106 @deffn {Scheme Procedure} port? x
107 @deffnx {C Function} scm_port_p (x)
108 Return a boolean indicating whether @var{x} is a port.
109 Equivalent to @code{(or (input-port? @var{x}) (output-port?
113 @deffn {Scheme Procedure} set-port-encoding! port enc
114 @deffnx {C Function} scm_set_port_encoding_x (port, enc)
115 Sets the character encoding that will be used to interpret all port I/O.
116 @var{enc} is a string containing the name of an encoding. Valid
117 encoding names are those
118 @url{http://www.iana.org/assignments/character-sets, defined by IANA}.
121 @defvr {Scheme Variable} %default-port-encoding
122 A fluid containing @code{#f} or the name of the encoding to
123 be used by default for newly created ports (@pxref{Fluids and Dynamic
124 States}). The value @code{#f} is equivalent to @code{"ISO-8859-1"}.
126 New ports are created with the encoding appropriate for the current
127 locale if @code{setlocale} has been called or the value specified by
128 this fluid otherwise.
131 @deffn {Scheme Procedure} port-encoding port
132 @deffnx {C Function} scm_port_encoding
133 Returns, as a string, the character encoding that @var{port} uses to
134 interpret its input and output.
137 @deffn {Scheme Procedure} set-port-conversion-strategy! port sym
138 @deffnx {C Function} scm_set_port_conversion_strategy_x (port, sym)
139 Sets the behavior of the interpreter when outputting a character that
140 is not representable in the port's current encoding. @var{sym} can be
141 either @code{'error}, @code{'substitute}, or @code{'escape}. If it is
142 @code{'error}, an error will be thrown when an nonconvertible character
143 is encountered. If it is @code{'substitute}, then nonconvertible
144 characters will be replaced with approximate characters, or with
145 question marks if no approximately correct character is available. If
146 it is @code{'escape}, it will appear as a hex escape when output.
148 If @var{port} is an open port, the conversion error behavior
149 is set for that port. If it is @code{#f}, it is set as the
150 default behavior for any future ports that get created in
154 @deffn {Scheme Procedure} port-conversion-strategy port
155 @deffnx {C Function} scm_port_conversion_strategy (port)
156 Returns the behavior of the port when outputting a character that is
157 not representable in the port's current encoding. It returns the
158 symbol @code{error} if unrepresentable characters should cause
159 exceptions, @code{substitute} if the port should try to replace
160 unrepresentable characters with question marks or approximate
161 characters, or @code{escape} if unrepresentable characters should be
162 converted to string escapes.
164 If @var{port} is @code{#f}, then the current default behavior will be
165 returned. New ports will have this default behavior when they are
175 [Generic procedures for reading from ports.]
178 @cindex End of file object
179 @deffn {Scheme Procedure} eof-object? x
180 @deffnx {C Function} scm_eof_object_p (x)
181 Return @code{#t} if @var{x} is an end-of-file object; otherwise
186 @deffn {Scheme Procedure} char-ready? [port]
187 @deffnx {C Function} scm_char_ready_p (port)
188 Return @code{#t} if a character is ready on input @var{port}
189 and return @code{#f} otherwise. If @code{char-ready?} returns
190 @code{#t} then the next @code{read-char} operation on
191 @var{port} is guaranteed not to hang. If @var{port} is a file
192 port at end of file then @code{char-ready?} returns @code{#t}.
194 @code{char-ready?} exists to make it possible for a
195 program to accept characters from interactive ports without
196 getting stuck waiting for input. Any input editors associated
197 with such ports must make sure that characters whose existence
198 has been asserted by @code{char-ready?} cannot be rubbed out.
199 If @code{char-ready?} were to return @code{#f} at end of file,
200 a port at end of file would be indistinguishable from an
201 interactive port that has no ready characters.
205 @deffn {Scheme Procedure} read-char [port]
206 @deffnx {C Function} scm_read_char (port)
207 Return the next character available from @var{port}, updating
208 @var{port} to point to the following character. If no more
209 characters are available, the end-of-file object is returned.
212 @deftypefn {C Function} size_t scm_c_read (SCM port, void *buffer, size_t size)
213 Read up to @var{size} bytes from @var{port} and store them in
214 @var{buffer}. The return value is the number of bytes actually read,
215 which can be less than @var{size} if end-of-file has been reached.
217 Note that this function does not update @code{port-line} and
218 @code{port-column} below.
222 @deffn {Scheme Procedure} peek-char [port]
223 @deffnx {C Function} scm_peek_char (port)
224 Return the next character available from @var{port},
225 @emph{without} updating @var{port} to point to the following
226 character. If no more characters are available, the
227 end-of-file object is returned.
229 The value returned by
230 a call to @code{peek-char} is the same as the value that would
231 have been returned by a call to @code{read-char} on the same
232 port. The only difference is that the very next call to
233 @code{read-char} or @code{peek-char} on that @var{port} will
234 return the value returned by the preceding call to
235 @code{peek-char}. In particular, a call to @code{peek-char} on
236 an interactive port will hang waiting for input whenever a call
237 to @code{read-char} would have hung.
240 @deffn {Scheme Procedure} unread-char cobj [port]
241 @deffnx {C Function} scm_unread_char (cobj, port)
242 Place @var{char} in @var{port} so that it will be read by the
243 next read operation. If called multiple times, the unread characters
244 will be read again in last-in first-out order. If @var{port} is
245 not supplied, the current input port is used.
248 @deffn {Scheme Procedure} unread-string str port
249 @deffnx {C Function} scm_unread_string (str, port)
250 Place the string @var{str} in @var{port} so that its characters will
251 be read from left-to-right as the next characters from @var{port}
252 during subsequent read operations. If called multiple times, the
253 unread characters will be read again in last-in first-out order. If
254 @var{port} is not supplied, the @code{current-input-port} is used.
257 @deffn {Scheme Procedure} drain-input port
258 @deffnx {C Function} scm_drain_input (port)
259 This procedure clears a port's input buffers, similar
260 to the way that force-output clears the output buffer. The
261 contents of the buffers are returned as a single string, e.g.,
264 (define p (open-input-file ...))
265 (drain-input p) => empty string, nothing buffered yet.
266 (unread-char (read-char p) p)
267 (drain-input p) => initial chars from p, up to the buffer size.
270 Draining the buffers may be useful for cleanly finishing
271 buffered I/O so that the file descriptor can be used directly
275 @deffn {Scheme Procedure} port-column port
276 @deffnx {Scheme Procedure} port-line port
277 @deffnx {C Function} scm_port_column (port)
278 @deffnx {C Function} scm_port_line (port)
279 Return the current column number or line number of @var{port}.
281 unknown, the result is #f. Otherwise, the result is a 0-origin integer
282 - i.e.@: the first character of the first line is line 0, column 0.
283 (However, when you display a file position, for example in an error
284 message, we recommend you add 1 to get 1-origin integers. This is
285 because lines and column numbers traditionally start with 1, and that is
286 what non-programmers will find most natural.)
289 @deffn {Scheme Procedure} set-port-column! port column
290 @deffnx {Scheme Procedure} set-port-line! port line
291 @deffnx {C Function} scm_set_port_column_x (port, column)
292 @deffnx {C Function} scm_set_port_line_x (port, line)
293 Set the current column or line number of @var{port}.
300 [Generic procedures for writing to ports.]
302 @deffn {Scheme Procedure} get-print-state port
303 @deffnx {C Function} scm_get_print_state (port)
304 Return the print state of the port @var{port}. If @var{port}
305 has no associated print state, @code{#f} is returned.
309 @deffn {Scheme Procedure} write obj [port]
310 Send a representation of @var{obj} to @var{port} or to the current
311 output port if not given.
313 The output is designed to be machine readable, and can be read back
314 with @code{read} (@pxref{Reading}). Strings are printed in
315 double quotes, with escapes if necessary, and characters are printed in
320 @deffn {Scheme Procedure} display obj [port]
321 Send a representation of @var{obj} to @var{port} or to the current
322 output port if not given.
324 The output is designed for human readability, it differs from
325 @code{write} in that strings are printed without double quotes and
326 escapes, and characters are printed as per @code{write-char}, not in
331 @deffn {Scheme Procedure} newline [port]
332 @deffnx {C Function} scm_newline (port)
333 Send a newline to @var{port}.
334 If @var{port} is omitted, send to the current output port.
337 @deffn {Scheme Procedure} port-with-print-state port [pstate]
338 @deffnx {C Function} scm_port_with_print_state (port, pstate)
339 Create a new port which behaves like @var{port}, but with an
340 included print state @var{pstate}. @var{pstate} is optional.
341 If @var{pstate} isn't supplied and @var{port} already has
342 a print state, the old print state is reused.
345 @deffn {Scheme Procedure} print-options-interface [setting]
346 @deffnx {C Function} scm_print_options (setting)
347 Option interface for the print options. Instead of using
348 this procedure directly, use the procedures
349 @code{print-enable}, @code{print-disable}, @code{print-set!}
350 and @code{print-options}.
353 @deffn {Scheme Procedure} simple-format destination message . args
354 @deffnx {C Function} scm_simple_format (destination, message, args)
355 Write @var{message} to @var{destination}, defaulting to
356 the current output port.
357 @var{message} can contain @code{~A} (was @code{%s}) and
358 @code{~S} (was @code{%S}) escapes. When printed,
359 the escapes are replaced with corresponding members of
361 @code{~A} formats using @code{display} and @code{~S} formats
363 If @var{destination} is @code{#t}, then use the current output
364 port, if @var{destination} is @code{#f}, then return a string
365 containing the formatted text. Does not add a trailing newline.
369 @deffn {Scheme Procedure} write-char chr [port]
370 @deffnx {C Function} scm_write_char (chr, port)
371 Send character @var{chr} to @var{port}.
374 @deftypefn {C Function} void scm_c_write (SCM port, const void *buffer, size_t size)
375 Write @var{size} bytes at @var{buffer} to @var{port}.
377 Note that this function does not update @code{port-line} and
378 @code{port-column} (@pxref{Reading}).
382 @deffn {Scheme Procedure} force-output [port]
383 @deffnx {C Function} scm_force_output (port)
384 Flush the specified output port, or the current output port if @var{port}
385 is omitted. The current output buffer contents are passed to the
386 underlying port implementation (e.g., in the case of fports, the
387 data will be written to the file and the output buffer will be cleared.)
388 It has no effect on an unbuffered port.
390 The return value is unspecified.
393 @deffn {Scheme Procedure} flush-all-ports
394 @deffnx {C Function} scm_flush_all_ports ()
395 Equivalent to calling @code{force-output} on
396 all open output ports. The return value is unspecified.
402 @cindex Closing ports
405 @deffn {Scheme Procedure} close-port port
406 @deffnx {C Function} scm_close_port (port)
407 Close the specified port object. Return @code{#t} if it
408 successfully closes a port or @code{#f} if it was already
409 closed. An exception may be raised if an error occurs, for
410 example when flushing buffered output. See also @ref{Ports and
411 File Descriptors, close}, for a procedure which can close file
415 @deffn {Scheme Procedure} close-input-port port
416 @deffnx {Scheme Procedure} close-output-port port
417 @deffnx {C Function} scm_close_input_port (port)
418 @deffnx {C Function} scm_close_output_port (port)
419 @rnindex close-input-port
420 @rnindex close-output-port
421 Close the specified input or output @var{port}. An exception may be
422 raised if an error occurs while closing. If @var{port} is already
423 closed, nothing is done. The return value is unspecified.
425 See also @ref{Ports and File Descriptors, close}, for a procedure
426 which can close file descriptors.
429 @deffn {Scheme Procedure} port-closed? port
430 @deffnx {C Function} scm_port_closed_p (port)
431 Return @code{#t} if @var{port} is closed or @code{#f} if it is
437 @subsection Random Access
438 @cindex Random access, ports
439 @cindex Port, random access
441 @deffn {Scheme Procedure} seek fd_port offset whence
442 @deffnx {C Function} scm_seek (fd_port, offset, whence)
443 Sets the current position of @var{fd/port} to the integer
444 @var{offset}, which is interpreted according to the value of
447 One of the following variables should be supplied for
450 Seek from the beginning of the file.
453 Seek from the current position.
456 Seek from the end of the file.
458 If @var{fd/port} is a file descriptor, the underlying system
459 call is @code{lseek}. @var{port} may be a string port.
461 The value returned is the new position in the file. This means
462 that the current position of a port can be obtained using:
464 (seek port 0 SEEK_CUR)
468 @deffn {Scheme Procedure} ftell fd_port
469 @deffnx {C Function} scm_ftell (fd_port)
470 Return an integer representing the current position of
471 @var{fd/port}, measured from the beginning. Equivalent to:
474 (seek port 0 SEEK_CUR)
480 @deffn {Scheme Procedure} truncate-file file [length]
481 @deffnx {C Function} scm_truncate_file (file, length)
482 Truncate @var{file} to @var{length} bytes. @var{file} can be a
483 filename string, a port object, or an integer file descriptor. The
484 return value is unspecified.
486 For a port or file descriptor @var{length} can be omitted, in which
487 case the file is truncated at the current position (per @code{ftell}
490 On most systems a file can be extended by giving a length greater than
491 the current size, but this is not mandatory in the POSIX standard.
495 @subsection Line Oriented and Delimited Text
496 @cindex Line input/output
497 @cindex Port, line input/output
499 The delimited-I/O module can be accessed with:
502 (use-modules (ice-9 rdelim))
505 It can be used to read or write lines of text, or read text delimited by
506 a specified set of characters. It's similar to the @code{(scsh rdelim)}
507 module from guile-scsh, but does not use multiple values or character
508 sets and has an extra procedure @code{write-line}.
510 @c begin (scm-doc-string "rdelim.scm" "read-line")
511 @deffn {Scheme Procedure} read-line [port] [handle-delim]
512 Return a line of text from @var{port} if specified, otherwise from the
513 value returned by @code{(current-input-port)}. Under Unix, a line of text
514 is terminated by the first end-of-line character or by end-of-file.
516 If @var{handle-delim} is specified, it should be one of the following
520 Discard the terminating delimiter. This is the default, but it will
521 be impossible to tell whether the read terminated with a delimiter or
524 Append the terminating delimiter (if any) to the returned string.
526 Push the terminating delimiter (if any) back on to the port.
528 Return a pair containing the string read from the port and the
529 terminating delimiter or end-of-file object.
533 @c begin (scm-doc-string "rdelim.scm" "read-line!")
534 @deffn {Scheme Procedure} read-line! buf [port]
535 Read a line of text into the supplied string @var{buf} and return the
536 number of characters added to @var{buf}. If @var{buf} is filled, then
537 @code{#f} is returned.
538 Read from @var{port} if
539 specified, otherwise from the value returned by @code{(current-input-port)}.
542 @c begin (scm-doc-string "rdelim.scm" "read-delimited")
543 @deffn {Scheme Procedure} read-delimited delims [port] [handle-delim]
544 Read text until one of the characters in the string @var{delims} is found
545 or end-of-file is reached. Read from @var{port} if supplied, otherwise
546 from the value returned by @code{(current-input-port)}.
547 @var{handle-delim} takes the same values as described for @code{read-line}.
550 @c begin (scm-doc-string "rdelim.scm" "read-delimited!")
551 @deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end]
552 Read text into the supplied string @var{buf} and return the number of
553 characters added to @var{buf} (subject to @var{handle-delim}, which takes
554 the same values specified for @code{read-line}. If @var{buf} is filled,
555 @code{#f} is returned for both the number of characters read and the
556 delimiter. Also terminates if one of the characters in the string
557 @var{delims} is found
558 or end-of-file is reached. Read from @var{port} if supplied, otherwise
559 from the value returned by @code{(current-input-port)}.
562 @deffn {Scheme Procedure} write-line obj [port]
563 @deffnx {C Function} scm_write_line (obj, port)
564 Display @var{obj} and a newline character to @var{port}. If
565 @var{port} is not specified, @code{(current-output-port)} is
566 used. This function is equivalent to:
573 Some of the aforementioned I/O functions rely on the following C
574 primitives. These will mainly be of interest to people hacking Guile
577 @deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]]
578 @deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end)
579 Read characters from @var{port} into @var{str} until one of the
580 characters in the @var{delims} string is encountered. If
581 @var{gobble} is true, discard the delimiter character;
582 otherwise, leave it in the input stream for the next read. If
583 @var{port} is not specified, use the value of
584 @code{(current-input-port)}. If @var{start} or @var{end} are
585 specified, store data only into the substring of @var{str}
586 bounded by @var{start} and @var{end} (which default to the
587 beginning and end of the string, respectively).
589 Return a pair consisting of the delimiter that terminated the
590 string and the number of characters read. If reading stopped
591 at the end of file, the delimiter returned is the
592 @var{eof-object}; if the string was filled without encountering
593 a delimiter, this value is @code{#f}.
596 @deffn {Scheme Procedure} %read-line [port]
597 @deffnx {C Function} scm_read_line (port)
598 Read a newline-terminated line from @var{port}, allocating storage as
599 necessary. The newline terminator (if any) is removed from the string,
600 and a pair consisting of the line and its delimiter is returned. The
601 delimiter may be either a newline or the @var{eof-object}; if
602 @code{%read-line} is called at the end of file, it returns the pair
603 @code{(#<eof> . #<eof>)}.
606 @node Block Reading and Writing
607 @subsection Block reading and writing
608 @cindex Block read/write
609 @cindex Port, block read/write
611 The Block-string-I/O module can be accessed with:
614 (use-modules (ice-9 rw))
617 It currently contains procedures that help to implement the
618 @code{(scsh rw)} module in guile-scsh.
620 @deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]]
621 @deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end)
622 Read characters from a port or file descriptor into a
623 string @var{str}. A port must have an underlying file
624 descriptor --- a so-called fport. This procedure is
625 scsh-compatible and can efficiently read large strings.
630 attempt to fill the entire string, unless the @var{start}
631 and/or @var{end} arguments are supplied. i.e., @var{start}
632 defaults to 0 and @var{end} defaults to
633 @code{(string-length str)}
635 use the current input port if @var{port_or_fdes} is not
638 return fewer than the requested number of characters in some
639 cases, e.g., on end of file, if interrupted by a signal, or if
640 not all the characters are immediately available.
642 wait indefinitely for some input if no characters are
644 unless the port is in non-blocking mode.
646 read characters from the port's input buffers if available,
647 instead from the underlying file descriptor.
649 return @code{#f} if end-of-file is encountered before reading
650 any characters, otherwise return the number of characters
653 return 0 if the port is in non-blocking mode and no characters
654 are immediately available.
656 return 0 if the request is for 0 bytes, with no
661 @deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]]
662 @deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end)
663 Write characters from a string @var{str} to a port or file
664 descriptor. A port must have an underlying file descriptor
665 --- a so-called fport. This procedure is
666 scsh-compatible and can efficiently write large strings.
671 attempt to write the entire string, unless the @var{start}
672 and/or @var{end} arguments are supplied. i.e., @var{start}
673 defaults to 0 and @var{end} defaults to
674 @code{(string-length str)}
676 use the current output port if @var{port_of_fdes} is not
679 in the case of a buffered port, store the characters in the
680 port's output buffer, if all will fit. If they will not fit
681 then any existing buffered characters will be flushed
683 to write the new characters directly to the underlying file
684 descriptor. If the port is in non-blocking mode and
685 buffered characters can not be flushed immediately, then an
686 @code{EAGAIN} system-error exception will be raised (Note:
687 scsh does not support the use of non-blocking buffered ports.)
689 write fewer than the requested number of
690 characters in some cases, e.g., if interrupted by a signal or
691 if not all of the output can be accepted immediately.
693 wait indefinitely for at least one character
694 from @var{str} to be accepted by the port, unless the port is
695 in non-blocking mode.
697 return the number of characters accepted by the port.
699 return 0 if the port is in non-blocking mode and can not accept
700 at least one character from @var{str} immediately
702 return 0 immediately if the request size is 0 bytes.
707 @subsection Default Ports for Input, Output and Errors
708 @cindex Default ports
709 @cindex Port, default
711 @rnindex current-input-port
712 @deffn {Scheme Procedure} current-input-port
713 @deffnx {C Function} scm_current_input_port ()
714 @cindex standard input
715 Return the current input port. This is the default port used
716 by many input procedures.
718 Initially this is the @dfn{standard input} in Unix and C terminology.
719 When the standard input is a tty the port is unbuffered, otherwise
722 Unbuffered input is good if an application runs an interactive
723 subprocess, since any type-ahead input won't go into Guile's buffer
724 and be unavailable to the subprocess.
726 Note that Guile buffering is completely separate from the tty ``line
727 discipline''. In the usual cooked mode on a tty Guile only sees a
728 line of input once the user presses @key{Return}.
731 @rnindex current-output-port
732 @deffn {Scheme Procedure} current-output-port
733 @deffnx {C Function} scm_current_output_port ()
734 @cindex standard output
735 Return the current output port. This is the default port used
736 by many output procedures.
738 Initially this is the @dfn{standard output} in Unix and C terminology.
739 When the standard output is a tty this port is unbuffered, otherwise
742 Unbuffered output to a tty is good for ensuring progress output or a
743 prompt is seen. But an application which always prints whole lines
744 could change to line buffered, or an application with a lot of output
745 could go fully buffered and perhaps make explicit @code{force-output}
746 calls (@pxref{Writing}) at selected points.
749 @deffn {Scheme Procedure} current-error-port
750 @deffnx {C Function} scm_current_error_port ()
751 @cindex standard error output
752 Return the port to which errors and warnings should be sent.
754 Initially this is the @dfn{standard error} in Unix and C terminology.
755 When the standard error is a tty this port is unbuffered, otherwise
759 @deffn {Scheme Procedure} set-current-input-port port
760 @deffnx {Scheme Procedure} set-current-output-port port
761 @deffnx {Scheme Procedure} set-current-error-port port
762 @deffnx {C Function} scm_set_current_input_port (port)
763 @deffnx {C Function} scm_set_current_output_port (port)
764 @deffnx {C Function} scm_set_current_error_port (port)
765 Change the ports returned by @code{current-input-port},
766 @code{current-output-port} and @code{current-error-port}, respectively,
767 so that they use the supplied @var{port} for input or output.
770 @deftypefn {C Function} void scm_dynwind_current_input_port (SCM port)
771 @deftypefnx {C Function} void scm_dynwind_current_output_port (SCM port)
772 @deftypefnx {C Function} void scm_dynwind_current_error_port (SCM port)
773 These functions must be used inside a pair of calls to
774 @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
775 Wind}). During the dynwind context, the indicated port is set to
778 More precisely, the current port is swapped with a `backup' value
779 whenever the dynwind context is entered or left. The backup value is
780 initialized with the @var{port} argument.
784 @subsection Types of Port
785 @cindex Types of ports
788 [Types of port; how to make them.]
791 * File Ports:: Ports on an operating system file.
792 * String Ports:: Ports on a Scheme string.
793 * Soft Ports:: Ports on arbitrary Scheme procedures.
794 * Void Ports:: Ports on nothing at all.
799 @subsubsection File Ports
803 The following procedures are used to open file ports.
804 See also @ref{Ports and File Descriptors, open}, for an interface
805 to the Unix @code{open} system call.
807 Most systems have limits on how many files can be open, so it's
808 strongly recommended that file ports be closed explicitly when no
809 longer required (@pxref{Ports}).
811 @deffn {Scheme Procedure} open-file filename mode
812 @deffnx {C Function} scm_open_file (filename, mode)
813 Open the file whose name is @var{filename}, and return a port
814 representing that file. The attributes of the port are
815 determined by the @var{mode} string. The way in which this is
816 interpreted is similar to C stdio. The first character must be
817 one of the following:
821 Open an existing file for input.
823 Open a file for output, creating it if it doesn't already exist
824 or removing its contents if it does.
826 Open a file for output, creating it if it doesn't already
827 exist. All writes to the port will go to the end of the file.
828 The "append mode" can be turned off while the port is in use
829 @pxref{Ports and File Descriptors, fcntl}
832 The following additional characters can be appended:
836 Open the port for both input and output. E.g., @code{r+}: open
837 an existing file for both input and output.
839 Create an "unbuffered" port. In this case input and output
840 operations are passed directly to the underlying port
841 implementation without additional buffering. This is likely to
842 slow down I/O operations. The buffering mode can be changed
843 while a port is in use @pxref{Ports and File Descriptors,
846 Add line-buffering to the port. The port output buffer will be
847 automatically flushed whenever a newline character is written.
849 Use binary mode. On DOS systems the default text mode converts CR+LF
850 in the file to newline for the program, whereas binary mode reads and
851 writes all bytes unchanged. On Unix-like systems there is no such
852 distinction, text files already contain just newlines and no
853 conversion is ever made. The @code{b} flag is accepted on all
854 systems, but has no effect on Unix-like systems.
856 (For reference, Guile leaves text versus binary up to the C library,
857 @code{b} here just adds @code{O_BINARY} to the underlying @code{open}
858 call, when that flag is available.)
861 If a file cannot be opened with the access
862 requested, @code{open-file} throws an exception.
864 In theory we could create read/write ports which were buffered
865 in one direction only. However this isn't included in the
869 @rnindex open-input-file
870 @deffn {Scheme Procedure} open-input-file filename
871 Open @var{filename} for input. Equivalent to
873 (open-file @var{filename} "r")
877 @rnindex open-output-file
878 @deffn {Scheme Procedure} open-output-file filename
879 Open @var{filename} for output. Equivalent to
881 (open-file @var{filename} "w")
885 @deffn {Scheme Procedure} call-with-input-file filename proc
886 @deffnx {Scheme Procedure} call-with-output-file filename proc
887 @rnindex call-with-input-file
888 @rnindex call-with-output-file
889 Open @var{filename} for input or output, and call @code{(@var{proc}
890 port)} with the resulting port. Return the value returned by
891 @var{proc}. @var{filename} is opened as per @code{open-input-file} or
892 @code{open-output-file} respectively, and an error is signaled if it
895 When @var{proc} returns, the port is closed. If @var{proc} does not
896 return (e.g.@: if it throws an error), then the port might not be
897 closed automatically, though it will be garbage collected in the usual
898 way if not otherwise referenced.
901 @deffn {Scheme Procedure} with-input-from-file filename thunk
902 @deffnx {Scheme Procedure} with-output-to-file filename thunk
903 @deffnx {Scheme Procedure} with-error-to-file filename thunk
904 @rnindex with-input-from-file
905 @rnindex with-output-to-file
906 Open @var{filename} and call @code{(@var{thunk})} with the new port
907 setup as respectively the @code{current-input-port},
908 @code{current-output-port}, or @code{current-error-port}. Return the
909 value returned by @var{thunk}. @var{filename} is opened as per
910 @code{open-input-file} or @code{open-output-file} respectively, and an
911 error is signaled if it cannot be opened.
913 When @var{thunk} returns, the port is closed and the previous setting
914 of the respective current port is restored.
916 The current port setting is managed with @code{dynamic-wind}, so the
917 previous value is restored no matter how @var{thunk} exits (eg.@: an
918 exception), and if @var{thunk} is re-entered (via a captured
919 continuation) then it's set again to the @var{FILENAME} port.
921 The port is closed when @var{thunk} returns normally, but not when
922 exited via an exception or new continuation. This ensures it's still
923 ready for use if @var{thunk} is re-entered by a captured continuation.
924 Of course the port is always garbage collected and closed in the usual
925 way when no longer referenced anywhere.
928 @deffn {Scheme Procedure} port-mode port
929 @deffnx {C Function} scm_port_mode (port)
930 Return the port modes associated with the open port @var{port}.
931 These will not necessarily be identical to the modes used when
932 the port was opened, since modes such as "append" which are
933 used only during port creation are not retained.
936 @deffn {Scheme Procedure} port-filename port
937 @deffnx {C Function} scm_port_filename (port)
938 Return the filename associated with @var{port}. This function returns
939 the strings "standard input", "standard output" and "standard error"
940 when called on the current input, output and error ports respectively.
942 @var{port} must be open, @code{port-filename} cannot be used once the
946 @deffn {Scheme Procedure} set-port-filename! port filename
947 @deffnx {C Function} scm_set_port_filename_x (port, filename)
948 Change the filename associated with @var{port}, using the current input
949 port if none is specified. Note that this does not change the port's
950 source of data, but only the value that is returned by
951 @code{port-filename} and reported in diagnostic output.
954 @deffn {Scheme Procedure} file-port? obj
955 @deffnx {C Function} scm_file_port_p (obj)
956 Determine whether @var{obj} is a port that is related to a file.
961 @subsubsection String Ports
965 The following allow string ports to be opened by analogy to R4R*
966 file port facilities:
968 With string ports, the port-encoding is treated differently than other
969 types of ports. When string ports are created, they do not inherit a
970 character encoding from the current locale. They are given a
971 default locale that allows them to handle all valid string characters.
972 Typically one should not modify a string port's character encoding
973 away from its default.
975 @deffn {Scheme Procedure} call-with-output-string proc
976 @deffnx {C Function} scm_call_with_output_string (proc)
977 Calls the one-argument procedure @var{proc} with a newly created output
978 port. When the function returns, the string composed of the characters
979 written into the port is returned. @var{proc} should not close the port.
981 Note that which characters can be written to a string port depend on the port's
982 encoding. The default encoding of string ports is specified by the
983 @code{%default-port-encoding} fluid (@pxref{Ports,
984 @code{%default-port-encoding}}). For instance, it is an error to write Greek
985 letter alpha to an ISO-8859-1-encoded string port since this character cannot be
986 represented with ISO-8859-1:
989 (define alpha (integer->char #x03b1)) ; GREEK SMALL LETTER ALPHA
991 (with-fluids ((%default-port-encoding "ISO-8859-1"))
992 (call-with-output-string
997 Throw to key `encoding-error'
1000 Changing the string port's encoding to a Unicode-capable encoding such as UTF-8
1004 @deffn {Scheme Procedure} call-with-input-string string proc
1005 @deffnx {C Function} scm_call_with_input_string (string, proc)
1006 Calls the one-argument procedure @var{proc} with a newly
1007 created input port from which @var{string}'s contents may be
1008 read. The value yielded by the @var{proc} is returned.
1011 @deffn {Scheme Procedure} with-output-to-string thunk
1012 Calls the zero-argument procedure @var{thunk} with the current output
1013 port set temporarily to a new string port. It returns a string
1014 composed of the characters written to the current output.
1016 See @code{call-with-output-string} above for character encoding considerations.
1019 @deffn {Scheme Procedure} with-input-from-string string thunk
1020 Calls the zero-argument procedure @var{thunk} with the current input
1021 port set temporarily to a string port opened on the specified
1022 @var{string}. The value yielded by @var{thunk} is returned.
1025 @deffn {Scheme Procedure} open-input-string str
1026 @deffnx {C Function} scm_open_input_string (str)
1027 Take a string and return an input port that delivers characters
1028 from the string. The port can be closed by
1029 @code{close-input-port}, though its storage will be reclaimed
1030 by the garbage collector if it becomes inaccessible.
1033 @deffn {Scheme Procedure} open-output-string
1034 @deffnx {C Function} scm_open_output_string ()
1035 Return an output port that will accumulate characters for
1036 retrieval by @code{get-output-string}. The port can be closed
1037 by the procedure @code{close-output-port}, though its storage
1038 will be reclaimed by the garbage collector if it becomes
1042 @deffn {Scheme Procedure} get-output-string port
1043 @deffnx {C Function} scm_get_output_string (port)
1044 Given an output port created by @code{open-output-string},
1045 return a string consisting of the characters that have been
1046 output to the port so far.
1048 @code{get-output-string} must be used before closing @var{port}, once
1049 closed the string cannot be obtained.
1052 A string port can be used in many procedures which accept a port
1053 but which are not dependent on implementation details of fports.
1054 E.g., seeking and truncating will work on a string port,
1055 but trying to extract the file descriptor number will fail.
1059 @subsubsection Soft Ports
1063 A @dfn{soft-port} is a port based on a vector of procedures capable of
1064 accepting or delivering characters. It allows emulation of I/O ports.
1066 @deffn {Scheme Procedure} make-soft-port pv modes
1067 @deffnx {C Function} scm_make_soft_port (pv, modes)
1068 Return a port capable of receiving or delivering characters as
1069 specified by the @var{modes} string (@pxref{File Ports,
1070 open-file}). @var{pv} must be a vector of length 5 or 6. Its
1071 components are as follows:
1075 procedure accepting one character for output
1077 procedure accepting a string for output
1079 thunk for flushing output
1081 thunk for getting one character
1083 thunk for closing port (not by garbage collection)
1085 (if present and not @code{#f}) thunk for computing the number of
1086 characters that can be read from the port without blocking.
1089 For an output-only port only elements 0, 1, 2, and 4 need be
1090 procedures. For an input-only port only elements 3 and 4 need
1091 be procedures. Thunks 2 and 4 can instead be @code{#f} if
1092 there is no useful operation for them to perform.
1094 If thunk 3 returns @code{#f} or an @code{eof-object}
1095 (@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
1096 Scheme}) it indicates that the port has reached end-of-file.
1100 (define stdout (current-output-port))
1101 (define p (make-soft-port
1103 (lambda (c) (write c stdout))
1104 (lambda (s) (display s stdout))
1105 (lambda () (display "." stdout))
1106 (lambda () (char-upcase (read-char)))
1107 (lambda () (display "@@" stdout)))
1110 (write p p) @result{} #<input-output: soft 8081e20>
1116 @subsubsection Void Ports
1120 This kind of port causes any data to be discarded when written to, and
1121 always returns the end-of-file object when read from.
1123 @deffn {Scheme Procedure} %make-void-port mode
1124 @deffnx {C Function} scm_sys_make_void_port (mode)
1125 Create and return a new void port. A void port acts like
1126 @file{/dev/null}. The @var{mode} argument
1127 specifies the input/output modes for this port: see the
1128 documentation for @code{open-file} in @ref{File Ports}.
1132 @node R6RS I/O Ports
1133 @subsection R6RS I/O Ports
1138 The I/O port API of the @uref{http://www.r6rs.org/, Revised Report^6 on
1139 the Algorithmic Language Scheme (R6RS)} is provided by the @code{(rnrs
1140 io ports)} module. It provides features, such as binary I/O and Unicode
1141 string I/O, that complement or refine Guile's historical port API
1142 presented above (@pxref{Input and Output}).
1144 @c FIXME: Update description when implemented.
1145 @emph{Note}: The implementation of this R6RS API is currently far from
1146 complete, notably due to the lack of support for Unicode I/O and strings.
1149 * R6RS End-of-File:: The end-of-file object.
1150 * R6RS Port Manipulation:: Manipulating R6RS ports.
1151 * R6RS Binary Input:: Binary input.
1152 * R6RS Binary Output:: Binary output.
1155 @node R6RS End-of-File
1156 @subsubsection The End-of-File Object
1161 R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io
1164 @deffn {Scheme Procedure} eof-object? obj
1165 @deffnx {C Function} scm_eof_object_p (obj)
1166 Return true if @var{obj} is the end-of-file (EOF) object.
1169 In addition, the following procedure is provided:
1171 @deffn {Scheme Procedure} eof-object
1172 @deffnx {C Function} scm_eof_object ()
1173 Return the end-of-file (EOF) object.
1176 (eof-object? (eof-object))
1182 @node R6RS Port Manipulation
1183 @subsubsection Port Manipulation
1185 The procedures listed below operate on any kind of R6RS I/O port.
1187 @deffn {Scheme Procedure} port-position port
1188 If @var{port} supports it (see below), return the offset (an integer)
1189 indicating where the next octet will be read from/written to in
1190 @var{port}. If @var{port} does not support this operation, an error
1191 condition is raised.
1193 This is similar to Guile's @code{seek} procedure with the
1194 @code{SEEK_CUR} argument (@pxref{Random Access}).
1197 @deffn {Scheme Procedure} port-has-port-position? port
1198 Return @code{#t} is @var{port} supports @code{port-position}.
1201 @deffn {Scheme Procedure} set-port-position! port offset
1202 If @var{port} supports it (see below), set the position where the next
1203 octet will be read from/written to @var{port} to @var{offset} (an
1204 integer). If @var{port} does not support this operation, an error
1205 condition is raised.
1207 This is similar to Guile's @code{seek} procedure with the
1208 @code{SEEK_SET} argument (@pxref{Random Access}).
1211 @deffn {Scheme Procedure} port-has-set-port-position!? port
1212 Return @code{#t} is @var{port} supports @code{set-port-position!}.
1215 @deffn {Scheme Procedure} call-with-port port proc
1216 Call @var{proc}, passing it @var{port} and closing @var{port} upon exit
1217 of @var{proc}. Return the return values of @var{proc}.
1221 @node R6RS Binary Input
1222 @subsubsection Binary Input
1224 @cindex binary input
1226 R6RS binary input ports can be created with the procedures described
1229 @deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder]
1230 @deffnx {C Function} scm_open_bytevector_input_port (bv, transcoder)
1231 Return an input port whose contents are drawn from bytevector @var{bv}
1232 (@pxref{Bytevectors}).
1234 @c FIXME: Update description when implemented.
1235 The @var{transcoder} argument is currently not supported.
1238 @cindex custom binary input ports
1240 @deffn {Scheme Procedure} make-custom-binary-input-port id read! get-position set-position! close
1241 @deffnx {C Function} scm_make_custom_binary_input_port (id, read!, get-position, set-position!, close)
1242 Return a new custom binary input port@footnote{This is similar in spirit
1243 to Guile's @dfn{soft ports} (@pxref{Soft Ports}).} named @var{id} (a
1244 string) whose input is drained by invoking @var{read!} and passing it a
1245 bytevector, an index where bytes should be written, and the number of
1246 bytes to read. The @code{read!} procedure must return an integer
1247 indicating the number of bytes read, or @code{0} to indicate the
1250 Optionally, if @var{get-position} is not @code{#f}, it must be a thunk
1251 that will be called when @var{port-position} is invoked on the custom
1252 binary port and should return an integer indicating the position within
1253 the underlying data stream; if @var{get-position} was not supplied, the
1254 returned port does not support @var{port-position}.
1256 Likewise, if @var{set-position!} is not @code{#f}, it should be a
1257 one-argument procedure. When @var{set-port-position!} is invoked on the
1258 custom binary input port, @var{set-position!} is passed an integer
1259 indicating the position of the next byte is to read.
1261 Finally, if @var{close} is not @code{#f}, it must be a thunk. It is
1262 invoked when the custom binary input port is closed.
1264 Using a custom binary input port, the @code{open-bytevector-input-port}
1265 procedure could be implemented as follows:
1268 (define (open-bytevector-input-port source)
1270 (define length (bytevector-length source))
1272 (define (read! bv start count)
1273 (let ((count (min count (- length position))))
1274 (bytevector-copy! source position
1276 (set! position (+ position count))
1279 (define (get-position) position)
1281 (define (set-position! new-position)
1282 (set! position new-position))
1284 (make-custom-binary-input-port "the port" read!
1288 (read (open-bytevector-input-port (string->utf8 "hello")))
1293 @cindex binary input
1294 Binary input is achieved using the procedures below:
1296 @deffn {Scheme Procedure} get-u8 port
1297 @deffnx {C Function} scm_get_u8 (port)
1298 Return an octet read from @var{port}, a binary input port, blocking as
1299 necessary, or the end-of-file object.
1302 @deffn {Scheme Procedure} lookahead-u8 port
1303 @deffnx {C Function} scm_lookahead_u8 (port)
1304 Like @code{get-u8} but does not update @var{port}'s position to point
1308 @deffn {Scheme Procedure} get-bytevector-n port count
1309 @deffnx {C Function} scm_get_bytevector_n (port, count)
1310 Read @var{count} octets from @var{port}, blocking as necessary and
1311 return a bytevector containing the octets read. If fewer bytes are
1312 available, a bytevector smaller than @var{count} is returned.
1315 @deffn {Scheme Procedure} get-bytevector-n! port bv start count
1316 @deffnx {C Function} scm_get_bytevector_n_x (port, bv, start, count)
1317 Read @var{count} bytes from @var{port} and store them in @var{bv}
1318 starting at index @var{start}. Return either the number of bytes
1319 actually read or the end-of-file object.
1322 @deffn {Scheme Procedure} get-bytevector-some port
1323 @deffnx {C Function} scm_get_bytevector_some (port)
1324 Read from @var{port}, blocking as necessary, until data are available or
1325 and end-of-file is reached. Return either a new bytevector containing
1326 the data read or the end-of-file object.
1329 @deffn {Scheme Procedure} get-bytevector-all port
1330 @deffnx {C Function} scm_get_bytevector_all (port)
1331 Read from @var{port}, blocking as necessary, until the end-of-file is
1332 reached. Return either a new bytevector containing the data read or the
1333 end-of-file object (if no data were available).
1336 @node R6RS Binary Output
1337 @subsubsection Binary Output
1339 Binary output ports can be created with the procedures below.
1341 @deffn {Scheme Procedure} open-bytevector-output-port [transcoder]
1342 @deffnx {C Function} scm_open_bytevector_output_port (transcoder)
1343 Return two values: a binary output port and a procedure. The latter
1344 should be called with zero arguments to obtain a bytevector containing
1345 the data accumulated by the port, as illustrated below.
1350 (open-bytevector-output-port))
1351 (lambda (port get-bytevector)
1352 (display "hello" port)
1355 @result{} #vu8(104 101 108 108 111)
1358 @c FIXME: Update description when implemented.
1359 The @var{transcoder} argument is currently not supported.
1362 @cindex custom binary output ports
1364 @deffn {Scheme Procedure} make-custom-binary-output-port id write! get-position set-position! close
1365 @deffnx {C Function} scm_make_custom_binary_output_port (id, write!, get-position, set-position!, close)
1366 Return a new custom binary output port named @var{id} (a string) whose
1367 output is sunk by invoking @var{write!} and passing it a bytevector, an
1368 index where bytes should be read from this bytevector, and the number of
1369 bytes to be ``written''. The @code{write!} procedure must return an
1370 integer indicating the number of bytes actually written; when it is
1371 passed @code{0} as the number of bytes to write, it should behave as
1372 though an end-of-file was sent to the byte sink.
1374 The other arguments are as for @code{make-custom-binary-input-port}
1375 (@pxref{R6RS Binary Input, @code{make-custom-binary-input-port}}).
1378 @cindex binary output
1379 Writing to a binary output port can be done using the following
1382 @deffn {Scheme Procedure} put-u8 port octet
1383 @deffnx {C Function} scm_put_u8 (port, octet)
1384 Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
1388 @deffn {Scheme Procedure} put-bytevector port bv [start [count]]
1389 @deffnx {C Function} scm_put_bytevector (port, bv, start, count)
1390 Write the contents of @var{bv} to @var{port}, optionally starting at
1391 index @var{start} and limiting to @var{count} octets.
1395 @node I/O Extensions
1396 @subsection Using and Extending Ports in C
1399 * C Port Interface:: Using ports from C.
1400 * Port Implementation:: How to implement a new port type in C.
1404 @node C Port Interface
1405 @subsubsection C Port Interface
1406 @cindex C port interface
1407 @cindex Port, C interface
1409 This section describes how to use Scheme ports from C.
1411 @subsubheading Port basics
1414 @tindex scm_ptob_descriptor
1416 @findex SCM_PTAB_ENTRY
1419 There are two main data structures. A port type object (ptob) is of
1420 type @code{scm_ptob_descriptor}. A port instance is of type
1421 @code{scm_port}. Given an @code{SCM} variable which points to a port,
1422 the corresponding C port object can be obtained using the
1423 @code{SCM_PTAB_ENTRY} macro. The ptob can be obtained by using
1424 @code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs}
1427 @subsubheading Port buffers
1429 An input port always has a read buffer and an output port always has a
1430 write buffer. However the size of these buffers is not guaranteed to be
1431 more than one byte (e.g., the @code{shortbuf} field in @code{scm_port}
1432 which is used when no other buffer is allocated). The way in which the
1433 buffers are allocated depends on the implementation of the ptob. For
1434 example in the case of an fport, buffers may be allocated with malloc
1435 when the port is created, but in the case of an strport the underlying
1436 string is used as the buffer.
1438 @subsubheading The @code{rw_random} flag
1440 Special treatment is required for ports which can be seeked at random.
1441 Before various operations, such as seeking the port or changing from
1442 input to output on a bidirectional port or vice versa, the port
1443 implementation must be given a chance to update its state. The write
1444 buffer is updated by calling the @code{flush} ptob procedure and the
1445 input buffer is updated by calling the @code{end_input} ptob procedure.
1446 In the case of an fport, @code{flush} causes buffered output to be
1447 written to the file descriptor, while @code{end_input} causes the
1448 descriptor position to be adjusted to account for buffered input which
1451 The special treatment must be performed if the @code{rw_random} flag in
1452 the port is non-zero.
1454 @subsubheading The @code{rw_active} variable
1456 The @code{rw_active} variable in the port is only used if
1457 @code{rw_random} is set. It's defined as an enum with the following
1462 the read buffer may have unread data.
1464 @item SCM_PORT_WRITE
1465 the write buffer may have unwritten data.
1467 @item SCM_PORT_NEITHER
1468 neither the write nor the read buffer has data.
1471 @subsubheading Reading from a port.
1473 To read from a port, it's possible to either call existing libguile
1474 procedures such as @code{scm_getc} and @code{scm_read_line} or to read
1475 data from the read buffer directly. Reading from the buffer involves
1476 the following steps:
1480 Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}.
1483 Fill the read buffer, if it's empty, using @code{scm_fill_input}.
1485 @item Read the data from the buffer and update the read position in
1486 the buffer. Steps 2) and 3) may be repeated as many times as required.
1488 @item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set.
1490 @item update the port's line and column counts.
1493 @subsubheading Writing to a port.
1495 To write data to a port, calling @code{scm_lfwrite} should be sufficient for
1496 most purposes. This takes care of the following steps:
1500 End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}.
1503 Pass the data to the ptob implementation using the @code{write} ptob
1504 procedure. The advantage of using the ptob @code{write} instead of
1505 manipulating the write buffer directly is that it allows the data to be
1506 written in one operation even if the port is using the single-byte
1510 Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random}
1515 @node Port Implementation
1516 @subsubsection Port Implementation
1517 @cindex Port implementation
1519 This section describes how to implement a new port type in C.
1521 As described in the previous section, a port type object (ptob) is
1522 a structure of type @code{scm_ptob_descriptor}. A ptob is created by
1523 calling @code{scm_make_port_type}.
1525 @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))
1526 Return a new port type object. The @var{name}, @var{fill_input} and
1527 @var{write} parameters are initial values for those port type fields,
1528 as described below. The other fields are initialized with default
1529 values and can be changed later.
1532 All of the elements of the ptob, apart from @code{name}, are procedures
1533 which collectively implement the port behaviour. Creating a new port
1534 type mostly involves writing these procedures.
1538 A pointer to a NUL terminated string: the name of the port type. This
1539 is the only element of @code{scm_ptob_descriptor} which is not
1540 a procedure. Set via the first argument to @code{scm_make_port_type}.
1543 Called during garbage collection to mark any SCM objects that a port
1544 object may contain. It doesn't need to be set unless the port has
1545 @code{SCM} components. Set using
1547 @deftypefun void scm_set_port_mark (scm_t_bits tc, SCM (*mark) (SCM port))
1551 Called when the port is collected during gc. It
1552 should free any resources used by the port.
1555 @deftypefun void scm_set_port_free (scm_t_bits tc, size_t (*free) (SCM port))
1559 Called when @code{write} is called on the port object, to print a
1560 port description. E.g., for an fport it may produce something like:
1561 @code{#<input: /etc/passwd 3>}. Set using
1563 @deftypefun void scm_set_port_print (scm_t_bits tc, int (*print) (SCM port, SCM dest_port, scm_print_state *pstate))
1564 The first argument @var{port} is the object being printed, the second
1565 argument @var{dest_port} is where its description should go.
1569 Not used at present. Set using
1571 @deftypefun void scm_set_port_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM))
1575 Called when the port is closed, unless it was collected during gc. It
1576 should free any resources used by the port.
1579 @deftypefun void scm_set_port_close (scm_t_bits tc, int (*close) (SCM port))
1583 Accept data which is to be written using the port. The port implementation
1584 may choose to buffer the data instead of processing it directly.
1585 Set via the third argument to @code{scm_make_port_type}.
1588 Complete the processing of buffered output data. Reset the value of
1589 @code{rw_active} to @code{SCM_PORT_NEITHER}.
1592 @deftypefun void scm_set_port_flush (scm_t_bits tc, void (*flush) (SCM port))
1596 Perform any synchronization required when switching from input to output
1597 on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}.
1600 @deftypefun void scm_set_port_end_input (scm_t_bits tc, void (*end_input) (SCM port, int offset))
1604 Read new data into the read buffer and return the first character. It
1605 can be assumed that the read buffer is empty when this procedure is called.
1606 Set via the second argument to @code{scm_make_port_type}.
1609 Return a lower bound on the number of bytes that could be read from the
1610 port without blocking. It can be assumed that the current state of
1611 @code{rw_active} is @code{SCM_PORT_NEITHER}.
1614 @deftypefun void scm_set_port_input_waiting (scm_t_bits tc, int (*input_waiting) (SCM port))
1618 Set the current position of the port. The procedure can not make
1619 any assumptions about the value of @code{rw_active} when it's
1620 called. It can reset the buffers first if desired by using something
1624 if (pt->rw_active == SCM_PORT_READ)
1625 scm_end_input (port);
1626 else if (pt->rw_active == SCM_PORT_WRITE)
1630 However note that this will have the side effect of discarding any data
1631 in the unread-char buffer, in addition to any side effects from the
1632 @code{end_input} and @code{flush} ptob procedures. This is undesirable
1633 when seek is called to measure the current position of the port, i.e.,
1634 @code{(seek p 0 SEEK_CUR)}. The libguile fport and string port
1635 implementations take care to avoid this problem.
1637 The procedure is set using
1639 @deftypefun void scm_set_port_seek (scm_t_bits tc, scm_t_off (*seek) (SCM port, scm_t_off offset, int whence))
1643 Truncate the port data to be specified length. It can be assumed that the
1644 current state of @code{rw_active} is @code{SCM_PORT_NEITHER}.
1647 @deftypefun void scm_set_port_truncate (scm_t_bits tc, void (*truncate) (SCM port, scm_t_off length))
1654 @c TeX-master: "guile.texi"