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 Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
9 @section Input and Output
12 * Ports:: The idea of the port abstraction.
13 * Reading:: Procedures for reading from a port.
14 * Writing:: Procedures for writing to a port.
15 * Closing:: Procedures to close a port.
16 * Random Access:: Moving around a random access port.
17 * Line/Delimited:: Read and write lines or delimited text.
18 * Block Reading and Writing:: Reading and writing blocks of text.
19 * Default Ports:: Defaults for input, output and errors.
20 * Port Types:: Types of port and how to make them.
21 * R6RS I/O Ports:: The R6RS port API.
22 * I/O Extensions:: Using and extending ports in C.
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 Each port also has an associated conversion strategy: what to do when
80 a Guile character can't be converted to the port's encoded character
81 representation for output. There are three possible strategies: to
82 raise an error, to replace the character with a hex escape, or to
83 replace the character with a substitute character.
86 @deffn {Scheme Procedure} input-port? x
87 @deffnx {C Function} scm_input_port_p (x)
88 Return @code{#t} if @var{x} is an input port, otherwise return
89 @code{#f}. Any object satisfying this predicate also satisfies
94 @deffn {Scheme Procedure} output-port? x
95 @deffnx {C Function} scm_output_port_p (x)
96 Return @code{#t} if @var{x} is an output port, otherwise return
97 @code{#f}. Any object satisfying this predicate also satisfies
101 @deffn {Scheme Procedure} port? x
102 @deffnx {C Function} scm_port_p (x)
103 Return a boolean indicating whether @var{x} is a port.
104 Equivalent to @code{(or (input-port? @var{x}) (output-port?
108 @deffn {Scheme Procedure} set-port-encoding! port enc
109 @deffnx {C Function} scm_set_port_encoding_x (port, enc)
110 Sets the character encoding that will be used to interpret all port
111 I/O. @var{enc} is a string containing the name of an encoding.
114 New ports are created with the encoding appropriate for the current
115 locale if @code{setlocale} has been called or ISO-8859-1 otherwise,
116 and this procedure can be used to modify that encoding.
118 @deffn {Scheme Procedure} port-encoding port
119 @deffnx {C Function} scm_port_encoding
120 Returns, as a string, the character encoding that @var{port} uses to
121 interpret its input and output.
124 @deffn {Scheme Procedure} set-port-conversion-strategy! port sym
125 @deffnx {C Function} scm_set_port_conversion_strategy_x (port, sym)
126 Sets the behavior of the interpreter when outputting a character that
127 is not representable in the port's current encoding. @var{sym} can be
128 either @code{'error}, @code{'substitute}, or @code{'escape}. If it is
129 @code{'error}, an error will be thrown when an nonconvertible character
130 is encountered. If it is @code{'substitute}, then nonconvertible
131 characters will be replaced with approximate characters, or with
132 question marks if no approximately correct character is available. If
133 it is @code{'escape}, it will appear as a hex escape when output.
135 If @var{port} is an open port, the conversion error behavior
136 is set for that port. If it is @code{#f}, it is set as the
137 default behavior for any future ports that get created in
141 @deffn {Scheme Procedure} port-conversion-strategy port
142 @deffnx {C Function} scm_port_conversion_strategy (port)
143 Returns the behavior of the port when outputting a character that is
144 not representable in the port's current encoding. It returns the
145 symbol @code{error} if unrepresentable characters should cause
146 exceptions, @code{substitute} if the port should try to replace
147 unrepresentable characters with question marks or approximate
148 characters, or @code{escape} if unrepresentable characters should be
149 converted to string escapes.
151 If @var{port} is @code{#f}, then the current default behavior will be
152 returned. New ports will have this default behavior when they are
162 [Generic procedures for reading from ports.]
165 @cindex End of file object
166 @deffn {Scheme Procedure} eof-object? x
167 @deffnx {C Function} scm_eof_object_p (x)
168 Return @code{#t} if @var{x} is an end-of-file object; otherwise
173 @deffn {Scheme Procedure} char-ready? [port]
174 @deffnx {C Function} scm_char_ready_p (port)
175 Return @code{#t} if a character is ready on input @var{port}
176 and return @code{#f} otherwise. If @code{char-ready?} returns
177 @code{#t} then the next @code{read-char} operation on
178 @var{port} is guaranteed not to hang. If @var{port} is a file
179 port at end of file then @code{char-ready?} returns @code{#t}.
181 @code{char-ready?} exists to make it possible for a
182 program to accept characters from interactive ports without
183 getting stuck waiting for input. Any input editors associated
184 with such ports must make sure that characters whose existence
185 has been asserted by @code{char-ready?} cannot be rubbed out.
186 If @code{char-ready?} were to return @code{#f} at end of file,
187 a port at end of file would be indistinguishable from an
188 interactive port that has no ready characters.
192 @deffn {Scheme Procedure} read-char [port]
193 @deffnx {C Function} scm_read_char (port)
194 Return the next character available from @var{port}, updating
195 @var{port} to point to the following character. If no more
196 characters are available, the end-of-file object is returned.
199 @deftypefn {C Function} size_t scm_c_read (SCM port, void *buffer, size_t size)
200 Read up to @var{size} bytes from @var{port} and store them in
201 @var{buffer}. The return value is the number of bytes actually read,
202 which can be less than @var{size} if end-of-file has been reached.
204 Note that this function does not update @code{port-line} and
205 @code{port-column} below.
209 @deffn {Scheme Procedure} peek-char [port]
210 @deffnx {C Function} scm_peek_char (port)
211 Return the next character available from @var{port},
212 @emph{without} updating @var{port} to point to the following
213 character. If no more characters are available, the
214 end-of-file object is returned.
216 The value returned by
217 a call to @code{peek-char} is the same as the value that would
218 have been returned by a call to @code{read-char} on the same
219 port. The only difference is that the very next call to
220 @code{read-char} or @code{peek-char} on that @var{port} will
221 return the value returned by the preceding call to
222 @code{peek-char}. In particular, a call to @code{peek-char} on
223 an interactive port will hang waiting for input whenever a call
224 to @code{read-char} would have hung.
227 @deffn {Scheme Procedure} unread-char cobj [port]
228 @deffnx {C Function} scm_unread_char (cobj, port)
229 Place @var{char} in @var{port} so that it will be read by the
230 next read operation. If called multiple times, the unread characters
231 will be read again in last-in first-out order. If @var{port} is
232 not supplied, the current input port is used.
235 @deffn {Scheme Procedure} unread-string str port
236 @deffnx {C Function} scm_unread_string (str, port)
237 Place the string @var{str} in @var{port} so that its characters will
238 be read from left-to-right as the next characters from @var{port}
239 during subsequent read operations. If called multiple times, the
240 unread characters will be read again in last-in first-out order. If
241 @var{port} is not supplied, the @code{current-input-port} is used.
244 @deffn {Scheme Procedure} drain-input port
245 @deffnx {C Function} scm_drain_input (port)
246 This procedure clears a port's input buffers, similar
247 to the way that force-output clears the output buffer. The
248 contents of the buffers are returned as a single string, e.g.,
251 (define p (open-input-file ...))
252 (drain-input p) => empty string, nothing buffered yet.
253 (unread-char (read-char p) p)
254 (drain-input p) => initial chars from p, up to the buffer size.
257 Draining the buffers may be useful for cleanly finishing
258 buffered I/O so that the file descriptor can be used directly
262 @deffn {Scheme Procedure} port-column port
263 @deffnx {Scheme Procedure} port-line port
264 @deffnx {C Function} scm_port_column (port)
265 @deffnx {C Function} scm_port_line (port)
266 Return the current column number or line number of @var{port}.
268 unknown, the result is #f. Otherwise, the result is a 0-origin integer
269 - i.e.@: the first character of the first line is line 0, column 0.
270 (However, when you display a file position, for example in an error
271 message, we recommend you add 1 to get 1-origin integers. This is
272 because lines and column numbers traditionally start with 1, and that is
273 what non-programmers will find most natural.)
276 @deffn {Scheme Procedure} set-port-column! port column
277 @deffnx {Scheme Procedure} set-port-line! port line
278 @deffnx {C Function} scm_set_port_column_x (port, column)
279 @deffnx {C Function} scm_set_port_line_x (port, line)
280 Set the current column or line number of @var{port}.
287 [Generic procedures for writing to ports.]
289 @deffn {Scheme Procedure} get-print-state port
290 @deffnx {C Function} scm_get_print_state (port)
291 Return the print state of the port @var{port}. If @var{port}
292 has no associated print state, @code{#f} is returned.
296 @deffn {Scheme Procedure} write obj [port]
297 Send a representation of @var{obj} to @var{port} or to the current
298 output port if not given.
300 The output is designed to be machine readable, and can be read back
301 with @code{read} (@pxref{Reading}). Strings are printed in
302 double quotes, with escapes if necessary, and characters are printed in
307 @deffn {Scheme Procedure} display obj [port]
308 Send a representation of @var{obj} to @var{port} or to the current
309 output port if not given.
311 The output is designed for human readability, it differs from
312 @code{write} in that strings are printed without double quotes and
313 escapes, and characters are printed as per @code{write-char}, not in
318 @deffn {Scheme Procedure} newline [port]
319 @deffnx {C Function} scm_newline (port)
320 Send a newline to @var{port}.
321 If @var{port} is omitted, send to the current output port.
324 @deffn {Scheme Procedure} port-with-print-state port [pstate]
325 @deffnx {C Function} scm_port_with_print_state (port, pstate)
326 Create a new port which behaves like @var{port}, but with an
327 included print state @var{pstate}. @var{pstate} is optional.
328 If @var{pstate} isn't supplied and @var{port} already has
329 a print state, the old print state is reused.
332 @deffn {Scheme Procedure} print-options-interface [setting]
333 @deffnx {C Function} scm_print_options (setting)
334 Option interface for the print options. Instead of using
335 this procedure directly, use the procedures
336 @code{print-enable}, @code{print-disable}, @code{print-set!}
337 and @code{print-options}.
340 @deffn {Scheme Procedure} simple-format destination message . args
341 @deffnx {C Function} scm_simple_format (destination, message, args)
342 Write @var{message} to @var{destination}, defaulting to
343 the current output port.
344 @var{message} can contain @code{~A} (was @code{%s}) and
345 @code{~S} (was @code{%S}) escapes. When printed,
346 the escapes are replaced with corresponding members of
348 @code{~A} formats using @code{display} and @code{~S} formats
350 If @var{destination} is @code{#t}, then use the current output
351 port, if @var{destination} is @code{#f}, then return a string
352 containing the formatted text. Does not add a trailing newline.
356 @deffn {Scheme Procedure} write-char chr [port]
357 @deffnx {C Function} scm_write_char (chr, port)
358 Send character @var{chr} to @var{port}.
361 @deftypefn {C Function} void scm_c_write (SCM port, const void *buffer, size_t size)
362 Write @var{size} bytes at @var{buffer} to @var{port}.
364 Note that this function does not update @code{port-line} and
365 @code{port-column} (@pxref{Reading}).
369 @deffn {Scheme Procedure} force-output [port]
370 @deffnx {C Function} scm_force_output (port)
371 Flush the specified output port, or the current output port if @var{port}
372 is omitted. The current output buffer contents are passed to the
373 underlying port implementation (e.g., in the case of fports, the
374 data will be written to the file and the output buffer will be cleared.)
375 It has no effect on an unbuffered port.
377 The return value is unspecified.
380 @deffn {Scheme Procedure} flush-all-ports
381 @deffnx {C Function} scm_flush_all_ports ()
382 Equivalent to calling @code{force-output} on
383 all open output ports. The return value is unspecified.
389 @cindex Closing ports
392 @deffn {Scheme Procedure} close-port port
393 @deffnx {C Function} scm_close_port (port)
394 Close the specified port object. Return @code{#t} if it
395 successfully closes a port or @code{#f} if it was already
396 closed. An exception may be raised if an error occurs, for
397 example when flushing buffered output. See also @ref{Ports and
398 File Descriptors, close}, for a procedure which can close file
402 @deffn {Scheme Procedure} close-input-port port
403 @deffnx {Scheme Procedure} close-output-port port
404 @deffnx {C Function} scm_close_input_port (port)
405 @deffnx {C Function} scm_close_output_port (port)
406 @rnindex close-input-port
407 @rnindex close-output-port
408 Close the specified input or output @var{port}. An exception may be
409 raised if an error occurs while closing. If @var{port} is already
410 closed, nothing is done. The return value is unspecified.
412 See also @ref{Ports and File Descriptors, close}, for a procedure
413 which can close file descriptors.
416 @deffn {Scheme Procedure} port-closed? port
417 @deffnx {C Function} scm_port_closed_p (port)
418 Return @code{#t} if @var{port} is closed or @code{#f} if it is
424 @subsection Random Access
425 @cindex Random access, ports
426 @cindex Port, random access
428 @deffn {Scheme Procedure} seek fd_port offset whence
429 @deffnx {C Function} scm_seek (fd_port, offset, whence)
430 Sets the current position of @var{fd/port} to the integer
431 @var{offset}, which is interpreted according to the value of
434 One of the following variables should be supplied for
437 Seek from the beginning of the file.
440 Seek from the current position.
443 Seek from the end of the file.
445 If @var{fd/port} is a file descriptor, the underlying system
446 call is @code{lseek}. @var{port} may be a string port.
448 The value returned is the new position in the file. This means
449 that the current position of a port can be obtained using:
451 (seek port 0 SEEK_CUR)
455 @deffn {Scheme Procedure} ftell fd_port
456 @deffnx {C Function} scm_ftell (fd_port)
457 Return an integer representing the current position of
458 @var{fd/port}, measured from the beginning. Equivalent to:
461 (seek port 0 SEEK_CUR)
467 @deffn {Scheme Procedure} truncate-file file [length]
468 @deffnx {C Function} scm_truncate_file (file, length)
469 Truncate @var{file} to @var{length} bytes. @var{file} can be a
470 filename string, a port object, or an integer file descriptor. The
471 return value is unspecified.
473 For a port or file descriptor @var{length} can be omitted, in which
474 case the file is truncated at the current position (per @code{ftell}
477 On most systems a file can be extended by giving a length greater than
478 the current size, but this is not mandatory in the POSIX standard.
482 @subsection Line Oriented and Delimited Text
483 @cindex Line input/output
484 @cindex Port, line input/output
486 The delimited-I/O module can be accessed with:
489 (use-modules (ice-9 rdelim))
492 It can be used to read or write lines of text, or read text delimited by
493 a specified set of characters. It's similar to the @code{(scsh rdelim)}
494 module from guile-scsh, but does not use multiple values or character
495 sets and has an extra procedure @code{write-line}.
497 @c begin (scm-doc-string "rdelim.scm" "read-line")
498 @deffn {Scheme Procedure} read-line [port] [handle-delim]
499 Return a line of text from @var{port} if specified, otherwise from the
500 value returned by @code{(current-input-port)}. Under Unix, a line of text
501 is terminated by the first end-of-line character or by end-of-file.
503 If @var{handle-delim} is specified, it should be one of the following
507 Discard the terminating delimiter. This is the default, but it will
508 be impossible to tell whether the read terminated with a delimiter or
511 Append the terminating delimiter (if any) to the returned string.
513 Push the terminating delimiter (if any) back on to the port.
515 Return a pair containing the string read from the port and the
516 terminating delimiter or end-of-file object.
520 @c begin (scm-doc-string "rdelim.scm" "read-line!")
521 @deffn {Scheme Procedure} read-line! buf [port]
522 Read a line of text into the supplied string @var{buf} and return the
523 number of characters added to @var{buf}. If @var{buf} is filled, then
524 @code{#f} is returned.
525 Read from @var{port} if
526 specified, otherwise from the value returned by @code{(current-input-port)}.
529 @c begin (scm-doc-string "rdelim.scm" "read-delimited")
530 @deffn {Scheme Procedure} read-delimited delims [port] [handle-delim]
531 Read text until one of the characters in the string @var{delims} is found
532 or end-of-file is reached. Read from @var{port} if supplied, otherwise
533 from the value returned by @code{(current-input-port)}.
534 @var{handle-delim} takes the same values as described for @code{read-line}.
537 @c begin (scm-doc-string "rdelim.scm" "read-delimited!")
538 @deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end]
539 Read text into the supplied string @var{buf} and return the number of
540 characters added to @var{buf} (subject to @var{handle-delim}, which takes
541 the same values specified for @code{read-line}. If @var{buf} is filled,
542 @code{#f} is returned for both the number of characters read and the
543 delimiter. Also terminates if one of the characters in the string
544 @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)}.
549 @deffn {Scheme Procedure} write-line obj [port]
550 @deffnx {C Function} scm_write_line (obj, port)
551 Display @var{obj} and a newline character to @var{port}. If
552 @var{port} is not specified, @code{(current-output-port)} is
553 used. This function is equivalent to:
560 Some of the aforementioned I/O functions rely on the following C
561 primitives. These will mainly be of interest to people hacking Guile
564 @deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]]
565 @deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end)
566 Read characters from @var{port} into @var{str} until one of the
567 characters in the @var{delims} string is encountered. If
568 @var{gobble} is true, discard the delimiter character;
569 otherwise, leave it in the input stream for the next read. If
570 @var{port} is not specified, use the value of
571 @code{(current-input-port)}. If @var{start} or @var{end} are
572 specified, store data only into the substring of @var{str}
573 bounded by @var{start} and @var{end} (which default to the
574 beginning and end of the string, respectively).
576 Return a pair consisting of the delimiter that terminated the
577 string and the number of characters read. If reading stopped
578 at the end of file, the delimiter returned is the
579 @var{eof-object}; if the string was filled without encountering
580 a delimiter, this value is @code{#f}.
583 @deffn {Scheme Procedure} %read-line [port]
584 @deffnx {C Function} scm_read_line (port)
585 Read a newline-terminated line from @var{port}, allocating storage as
586 necessary. The newline terminator (if any) is removed from the string,
587 and a pair consisting of the line and its delimiter is returned. The
588 delimiter may be either a newline or the @var{eof-object}; if
589 @code{%read-line} is called at the end of file, it returns the pair
590 @code{(#<eof> . #<eof>)}.
593 @node Block Reading and Writing
594 @subsection Block reading and writing
595 @cindex Block read/write
596 @cindex Port, block read/write
598 The Block-string-I/O module can be accessed with:
601 (use-modules (ice-9 rw))
604 It currently contains procedures that help to implement the
605 @code{(scsh rw)} module in guile-scsh.
607 @deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]]
608 @deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end)
609 Read characters from a port or file descriptor into a
610 string @var{str}. A port must have an underlying file
611 descriptor --- a so-called fport. This procedure is
612 scsh-compatible and can efficiently read large strings.
617 attempt to fill the entire string, unless the @var{start}
618 and/or @var{end} arguments are supplied. i.e., @var{start}
619 defaults to 0 and @var{end} defaults to
620 @code{(string-length str)}
622 use the current input port if @var{port_or_fdes} is not
625 return fewer than the requested number of characters in some
626 cases, e.g., on end of file, if interrupted by a signal, or if
627 not all the characters are immediately available.
629 wait indefinitely for some input if no characters are
631 unless the port is in non-blocking mode.
633 read characters from the port's input buffers if available,
634 instead from the underlying file descriptor.
636 return @code{#f} if end-of-file is encountered before reading
637 any characters, otherwise return the number of characters
640 return 0 if the port is in non-blocking mode and no characters
641 are immediately available.
643 return 0 if the request is for 0 bytes, with no
648 @deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]]
649 @deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end)
650 Write characters from a string @var{str} to a port or file
651 descriptor. A port must have an underlying file descriptor
652 --- a so-called fport. This procedure is
653 scsh-compatible and can efficiently write large strings.
658 attempt to write the entire string, unless the @var{start}
659 and/or @var{end} arguments are supplied. i.e., @var{start}
660 defaults to 0 and @var{end} defaults to
661 @code{(string-length str)}
663 use the current output port if @var{port_of_fdes} is not
666 in the case of a buffered port, store the characters in the
667 port's output buffer, if all will fit. If they will not fit
668 then any existing buffered characters will be flushed
670 to write the new characters directly to the underlying file
671 descriptor. If the port is in non-blocking mode and
672 buffered characters can not be flushed immediately, then an
673 @code{EAGAIN} system-error exception will be raised (Note:
674 scsh does not support the use of non-blocking buffered ports.)
676 write fewer than the requested number of
677 characters in some cases, e.g., if interrupted by a signal or
678 if not all of the output can be accepted immediately.
680 wait indefinitely for at least one character
681 from @var{str} to be accepted by the port, unless the port is
682 in non-blocking mode.
684 return the number of characters accepted by the port.
686 return 0 if the port is in non-blocking mode and can not accept
687 at least one character from @var{str} immediately
689 return 0 immediately if the request size is 0 bytes.
694 @subsection Default Ports for Input, Output and Errors
695 @cindex Default ports
696 @cindex Port, default
698 @rnindex current-input-port
699 @deffn {Scheme Procedure} current-input-port
700 @deffnx {C Function} scm_current_input_port ()
701 @cindex standard input
702 Return the current input port. This is the default port used
703 by many input procedures.
705 Initially this is the @dfn{standard input} in Unix and C terminology.
706 When the standard input is a tty the port is unbuffered, otherwise
709 Unbuffered input is good if an application runs an interactive
710 subprocess, since any type-ahead input won't go into Guile's buffer
711 and be unavailable to the subprocess.
713 Note that Guile buffering is completely separate from the tty ``line
714 discipline''. In the usual cooked mode on a tty Guile only sees a
715 line of input once the user presses @key{Return}.
718 @rnindex current-output-port
719 @deffn {Scheme Procedure} current-output-port
720 @deffnx {C Function} scm_current_output_port ()
721 @cindex standard output
722 Return the current output port. This is the default port used
723 by many output procedures.
725 Initially this is the @dfn{standard output} in Unix and C terminology.
726 When the standard output is a tty this port is unbuffered, otherwise
729 Unbuffered output to a tty is good for ensuring progress output or a
730 prompt is seen. But an application which always prints whole lines
731 could change to line buffered, or an application with a lot of output
732 could go fully buffered and perhaps make explicit @code{force-output}
733 calls (@pxref{Writing}) at selected points.
736 @deffn {Scheme Procedure} current-error-port
737 @deffnx {C Function} scm_current_error_port ()
738 @cindex standard error output
739 Return the port to which errors and warnings should be sent.
741 Initially this is the @dfn{standard error} in Unix and C terminology.
742 When the standard error is a tty this port is unbuffered, otherwise
746 @deffn {Scheme Procedure} set-current-input-port port
747 @deffnx {Scheme Procedure} set-current-output-port port
748 @deffnx {Scheme Procedure} set-current-error-port port
749 @deffnx {C Function} scm_set_current_input_port (port)
750 @deffnx {C Function} scm_set_current_output_port (port)
751 @deffnx {C Function} scm_set_current_error_port (port)
752 Change the ports returned by @code{current-input-port},
753 @code{current-output-port} and @code{current-error-port}, respectively,
754 so that they use the supplied @var{port} for input or output.
757 @deftypefn {C Function} void scm_dynwind_current_input_port (SCM port)
758 @deftypefnx {C Function} void scm_dynwind_current_output_port (SCM port)
759 @deftypefnx {C Function} void scm_dynwind_current_error_port (SCM port)
760 These functions must be used inside a pair of calls to
761 @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
762 Wind}). During the dynwind context, the indicated port is set to
765 More precisely, the current port is swapped with a `backup' value
766 whenever the dynwind context is entered or left. The backup value is
767 initialized with the @var{port} argument.
771 @subsection Types of Port
772 @cindex Types of ports
775 [Types of port; how to make them.]
778 * File Ports:: Ports on an operating system file.
779 * String Ports:: Ports on a Scheme string.
780 * Soft Ports:: Ports on arbitrary Scheme procedures.
781 * Void Ports:: Ports on nothing at all.
786 @subsubsection File Ports
790 The following procedures are used to open file ports.
791 See also @ref{Ports and File Descriptors, open}, for an interface
792 to the Unix @code{open} system call.
794 Most systems have limits on how many files can be open, so it's
795 strongly recommended that file ports be closed explicitly when no
796 longer required (@pxref{Ports}).
798 @deffn {Scheme Procedure} open-file filename mode
799 @deffnx {C Function} scm_open_file (filename, mode)
800 Open the file whose name is @var{filename}, and return a port
801 representing that file. The attributes of the port are
802 determined by the @var{mode} string. The way in which this is
803 interpreted is similar to C stdio. The first character must be
804 one of the following:
808 Open an existing file for input.
810 Open a file for output, creating it if it doesn't already exist
811 or removing its contents if it does.
813 Open a file for output, creating it if it doesn't already
814 exist. All writes to the port will go to the end of the file.
815 The "append mode" can be turned off while the port is in use
816 @pxref{Ports and File Descriptors, fcntl}
819 The following additional characters can be appended:
823 Open the port for both input and output. E.g., @code{r+}: open
824 an existing file for both input and output.
826 Create an "unbuffered" port. In this case input and output
827 operations are passed directly to the underlying port
828 implementation without additional buffering. This is likely to
829 slow down I/O operations. The buffering mode can be changed
830 while a port is in use @pxref{Ports and File Descriptors,
833 Add line-buffering to the port. The port output buffer will be
834 automatically flushed whenever a newline character is written.
836 Use binary mode. On DOS systems the default text mode converts CR+LF
837 in the file to newline for the program, whereas binary mode reads and
838 writes all bytes unchanged. On Unix-like systems there is no such
839 distinction, text files already contain just newlines and no
840 conversion is ever made. The @code{b} flag is accepted on all
841 systems, but has no effect on Unix-like systems.
843 (For reference, Guile leaves text versus binary up to the C library,
844 @code{b} here just adds @code{O_BINARY} to the underlying @code{open}
845 call, when that flag is available.)
848 If a file cannot be opened with the access
849 requested, @code{open-file} throws an exception.
851 In theory we could create read/write ports which were buffered
852 in one direction only. However this isn't included in the
856 @rnindex open-input-file
857 @deffn {Scheme Procedure} open-input-file filename
858 Open @var{filename} for input. Equivalent to
860 (open-file @var{filename} "r")
864 @rnindex open-output-file
865 @deffn {Scheme Procedure} open-output-file filename
866 Open @var{filename} for output. Equivalent to
868 (open-file @var{filename} "w")
872 @deffn {Scheme Procedure} call-with-input-file filename proc
873 @deffnx {Scheme Procedure} call-with-output-file filename proc
874 @rnindex call-with-input-file
875 @rnindex call-with-output-file
876 Open @var{filename} for input or output, and call @code{(@var{proc}
877 port)} with the resulting port. Return the value returned by
878 @var{proc}. @var{filename} is opened as per @code{open-input-file} or
879 @code{open-output-file} respectively, and an error is signaled if it
882 When @var{proc} returns, the port is closed. If @var{proc} does not
883 return (e.g.@: if it throws an error), then the port might not be
884 closed automatically, though it will be garbage collected in the usual
885 way if not otherwise referenced.
888 @deffn {Scheme Procedure} with-input-from-file filename thunk
889 @deffnx {Scheme Procedure} with-output-to-file filename thunk
890 @deffnx {Scheme Procedure} with-error-to-file filename thunk
891 @rnindex with-input-from-file
892 @rnindex with-output-to-file
893 Open @var{filename} and call @code{(@var{thunk})} with the new port
894 setup as respectively the @code{current-input-port},
895 @code{current-output-port}, or @code{current-error-port}. Return the
896 value returned by @var{thunk}. @var{filename} is opened as per
897 @code{open-input-file} or @code{open-output-file} respectively, and an
898 error is signaled if it cannot be opened.
900 When @var{thunk} returns, the port is closed and the previous setting
901 of the respective current port is restored.
903 The current port setting is managed with @code{dynamic-wind}, so the
904 previous value is restored no matter how @var{thunk} exits (eg.@: an
905 exception), and if @var{thunk} is re-entered (via a captured
906 continuation) then it's set again to the @var{FILENAME} port.
908 The port is closed when @var{thunk} returns normally, but not when
909 exited via an exception or new continuation. This ensures it's still
910 ready for use if @var{thunk} is re-entered by a captured continuation.
911 Of course the port is always garbage collected and closed in the usual
912 way when no longer referenced anywhere.
915 @deffn {Scheme Procedure} port-mode port
916 @deffnx {C Function} scm_port_mode (port)
917 Return the port modes associated with the open port @var{port}.
918 These will not necessarily be identical to the modes used when
919 the port was opened, since modes such as "append" which are
920 used only during port creation are not retained.
923 @deffn {Scheme Procedure} port-filename port
924 @deffnx {C Function} scm_port_filename (port)
925 Return the filename associated with @var{port}. This function returns
926 the strings "standard input", "standard output" and "standard error"
927 when called on the current input, output and error ports respectively.
929 @var{port} must be open, @code{port-filename} cannot be used once the
933 @deffn {Scheme Procedure} set-port-filename! port filename
934 @deffnx {C Function} scm_set_port_filename_x (port, filename)
935 Change the filename associated with @var{port}, using the current input
936 port if none is specified. Note that this does not change the port's
937 source of data, but only the value that is returned by
938 @code{port-filename} and reported in diagnostic output.
941 @deffn {Scheme Procedure} file-port? obj
942 @deffnx {C Function} scm_file_port_p (obj)
943 Determine whether @var{obj} is a port that is related to a file.
948 @subsubsection String Ports
952 The following allow string ports to be opened by analogy to R4R*
953 file port facilities:
955 With string ports, the port-encoding is treated differently than other
956 types of ports. When string ports are created, they do not inherit a
957 character encoding from the current locale. They are given a
958 default locale that allows them to handle all valid string characters.
959 Typically one should not modify a string port's character encoding
960 away from its default.
962 @deffn {Scheme Procedure} call-with-output-string proc
963 @deffnx {C Function} scm_call_with_output_string (proc)
964 Calls the one-argument procedure @var{proc} with a newly created output
965 port. When the function returns, the string composed of the characters
966 written into the port is returned. @var{proc} should not close the port.
969 @deffn {Scheme Procedure} call-with-input-string string proc
970 @deffnx {C Function} scm_call_with_input_string (string, proc)
971 Calls the one-argument procedure @var{proc} with a newly
972 created input port from which @var{string}'s contents may be
973 read. The value yielded by the @var{proc} is returned.
976 @deffn {Scheme Procedure} with-output-to-string thunk
977 Calls the zero-argument procedure @var{thunk} with the current output
978 port set temporarily to a new string port. It returns a string
979 composed of the characters written to the current output.
982 @deffn {Scheme Procedure} with-input-from-string string thunk
983 Calls the zero-argument procedure @var{thunk} with the current input
984 port set temporarily to a string port opened on the specified
985 @var{string}. The value yielded by @var{thunk} is returned.
988 @deffn {Scheme Procedure} open-input-string str
989 @deffnx {C Function} scm_open_input_string (str)
990 Take a string and return an input port that delivers characters
991 from the string. The port can be closed by
992 @code{close-input-port}, though its storage will be reclaimed
993 by the garbage collector if it becomes inaccessible.
996 @deffn {Scheme Procedure} open-output-string
997 @deffnx {C Function} scm_open_output_string ()
998 Return an output port that will accumulate characters for
999 retrieval by @code{get-output-string}. The port can be closed
1000 by the procedure @code{close-output-port}, though its storage
1001 will be reclaimed by the garbage collector if it becomes
1005 @deffn {Scheme Procedure} get-output-string port
1006 @deffnx {C Function} scm_get_output_string (port)
1007 Given an output port created by @code{open-output-string},
1008 return a string consisting of the characters that have been
1009 output to the port so far.
1011 @code{get-output-string} must be used before closing @var{port}, once
1012 closed the string cannot be obtained.
1015 A string port can be used in many procedures which accept a port
1016 but which are not dependent on implementation details of fports.
1017 E.g., seeking and truncating will work on a string port,
1018 but trying to extract the file descriptor number will fail.
1022 @subsubsection Soft Ports
1026 A @dfn{soft-port} is a port based on a vector of procedures capable of
1027 accepting or delivering characters. It allows emulation of I/O ports.
1029 @deffn {Scheme Procedure} make-soft-port pv modes
1030 @deffnx {C Function} scm_make_soft_port (pv, modes)
1031 Return a port capable of receiving or delivering characters as
1032 specified by the @var{modes} string (@pxref{File Ports,
1033 open-file}). @var{pv} must be a vector of length 5 or 6. Its
1034 components are as follows:
1038 procedure accepting one character for output
1040 procedure accepting a string for output
1042 thunk for flushing output
1044 thunk for getting one character
1046 thunk for closing port (not by garbage collection)
1048 (if present and not @code{#f}) thunk for computing the number of
1049 characters that can be read from the port without blocking.
1052 For an output-only port only elements 0, 1, 2, and 4 need be
1053 procedures. For an input-only port only elements 3 and 4 need
1054 be procedures. Thunks 2 and 4 can instead be @code{#f} if
1055 there is no useful operation for them to perform.
1057 If thunk 3 returns @code{#f} or an @code{eof-object}
1058 (@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
1059 Scheme}) it indicates that the port has reached end-of-file.
1063 (define stdout (current-output-port))
1064 (define p (make-soft-port
1066 (lambda (c) (write c stdout))
1067 (lambda (s) (display s stdout))
1068 (lambda () (display "." stdout))
1069 (lambda () (char-upcase (read-char)))
1070 (lambda () (display "@@" stdout)))
1073 (write p p) @result{} #<input-output: soft 8081e20>
1079 @subsubsection Void Ports
1083 This kind of port causes any data to be discarded when written to, and
1084 always returns the end-of-file object when read from.
1086 @deffn {Scheme Procedure} %make-void-port mode
1087 @deffnx {C Function} scm_sys_make_void_port (mode)
1088 Create and return a new void port. A void port acts like
1089 @file{/dev/null}. The @var{mode} argument
1090 specifies the input/output modes for this port: see the
1091 documentation for @code{open-file} in @ref{File Ports}.
1095 @node R6RS I/O Ports
1096 @subsection R6RS I/O Ports
1101 The I/O port API of the @uref{http://www.r6rs.org/, Revised Report^6 on
1102 the Algorithmic Language Scheme (R6RS)} is provided by the @code{(rnrs
1103 io ports)} module. It provides features, such as binary I/O and Unicode
1104 string I/O, that complement or refine Guile's historical port API
1105 presented above (@pxref{Input and Output}).
1107 @c FIXME: Update description when implemented.
1108 @emph{Note}: The implementation of this R6RS API is currently far from
1109 complete, notably due to the lack of support for Unicode I/O and strings.
1112 * R6RS End-of-File:: The end-of-file object.
1113 * R6RS Port Manipulation:: Manipulating R6RS ports.
1114 * R6RS Binary Input:: Binary input.
1115 * R6RS Binary Output:: Binary output.
1118 @node R6RS End-of-File
1119 @subsubsection The End-of-File Object
1124 R5RS' @code{eof-object?} procedure is provided by the @code{(rnrs io
1127 @deffn {Scheme Procedure} eof-object? obj
1128 @deffnx {C Function} scm_eof_object_p (obj)
1129 Return true if @var{obj} is the end-of-file (EOF) object.
1132 In addition, the following procedure is provided:
1134 @deffn {Scheme Procedure} eof-object
1135 @deffnx {C Function} scm_eof_object ()
1136 Return the end-of-file (EOF) object.
1139 (eof-object? (eof-object))
1145 @node R6RS Port Manipulation
1146 @subsubsection Port Manipulation
1148 The procedures listed below operate on any kind of R6RS I/O port.
1150 @deffn {Scheme Procedure} port-position port
1151 If @var{port} supports it (see below), return the offset (an integer)
1152 indicating where the next octet will be read from/written to in
1153 @var{port}. If @var{port} does not support this operation, an error
1154 condition is raised.
1156 This is similar to Guile's @code{seek} procedure with the
1157 @code{SEEK_CUR} argument (@pxref{Random Access}).
1160 @deffn {Scheme Procedure} port-has-port-position? port
1161 Return @code{#t} is @var{port} supports @code{port-position}.
1164 @deffn {Scheme Procedure} set-port-position! port offset
1165 If @var{port} supports it (see below), set the position where the next
1166 octet will be read from/written to @var{port} to @var{offset} (an
1167 integer). If @var{port} does not support this operation, an error
1168 condition is raised.
1170 This is similar to Guile's @code{seek} procedure with the
1171 @code{SEEK_SET} argument (@pxref{Random Access}).
1174 @deffn {Scheme Procedure} port-has-set-port-position!? port
1175 Return @code{#t} is @var{port} supports @code{set-port-position!}.
1178 @deffn {Scheme Procedure} call-with-port port proc
1179 Call @var{proc}, passing it @var{port} and closing @var{port} upon exit
1180 of @var{proc}. Return the return values of @var{proc}.
1184 @node R6RS Binary Input
1185 @subsubsection Binary Input
1187 @cindex binary input
1189 R6RS binary input ports can be created with the procedures described
1192 @deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder]
1193 @deffnx {C Function} scm_open_bytevector_input_port (bv, transcoder)
1194 Return an input port whose contents are drawn from bytevector @var{bv}
1195 (@pxref{Bytevectors}).
1197 @c FIXME: Update description when implemented.
1198 The @var{transcoder} argument is currently not supported.
1201 @cindex custom binary input ports
1203 @deffn {Scheme Procedure} make-custom-binary-input-port id read! get-position set-position! close
1204 @deffnx {C Function} scm_make_custom_binary_input_port (id, read!, get-position, set-position!, close)
1205 Return a new custom binary input port@footnote{This is similar in spirit
1206 to Guile's @dfn{soft ports} (@pxref{Soft Ports}).} named @var{id} (a
1207 string) whose input is drained by invoking @var{read!} and passing it a
1208 bytevector, an index where bytes should be written, and the number of
1209 bytes to read. The @code{read!} procedure must return an integer
1210 indicating the number of bytes read, or @code{0} to indicate the
1213 Optionally, if @var{get-position} is not @code{#f}, it must be a thunk
1214 that will be called when @var{port-position} is invoked on the custom
1215 binary port and should return an integer indicating the position within
1216 the underlying data stream; if @var{get-position} was not supplied, the
1217 returned port does not support @var{port-position}.
1219 Likewise, if @var{set-position!} is not @code{#f}, it should be a
1220 one-argument procedure. When @var{set-port-position!} is invoked on the
1221 custom binary input port, @var{set-position!} is passed an integer
1222 indicating the position of the next byte is to read.
1224 Finally, if @var{close} is not @code{#f}, it must be a thunk. It is
1225 invoked when the custom binary input port is closed.
1227 Using a custom binary input port, the @code{open-bytevector-input-port}
1228 procedure could be implemented as follows:
1231 (define (open-bytevector-input-port source)
1233 (define length (bytevector-length source))
1235 (define (read! bv start count)
1236 (let ((count (min count (- length position))))
1237 (bytevector-copy! source position
1239 (set! position (+ position count))
1242 (define (get-position) position)
1244 (define (set-position! new-position)
1245 (set! position new-position))
1247 (make-custom-binary-input-port "the port" read!
1251 (read (open-bytevector-input-port (string->utf8 "hello")))
1256 @cindex binary input
1257 Binary input is achieved using the procedures below:
1259 @deffn {Scheme Procedure} get-u8 port
1260 @deffnx {C Function} scm_get_u8 (port)
1261 Return an octet read from @var{port}, a binary input port, blocking as
1262 necessary, or the end-of-file object.
1265 @deffn {Scheme Procedure} lookahead-u8 port
1266 @deffnx {C Function} scm_lookahead_u8 (port)
1267 Like @code{get-u8} but does not update @var{port}'s position to point
1271 @deffn {Scheme Procedure} get-bytevector-n port count
1272 @deffnx {C Function} scm_get_bytevector_n (port, count)
1273 Read @var{count} octets from @var{port}, blocking as necessary and
1274 return a bytevector containing the octets read. If fewer bytes are
1275 available, a bytevector smaller than @var{count} is returned.
1278 @deffn {Scheme Procedure} get-bytevector-n! port bv start count
1279 @deffnx {C Function} scm_get_bytevector_n_x (port, bv, start, count)
1280 Read @var{count} bytes from @var{port} and store them in @var{bv}
1281 starting at index @var{start}. Return either the number of bytes
1282 actually read or the end-of-file object.
1285 @deffn {Scheme Procedure} get-bytevector-some port
1286 @deffnx {C Function} scm_get_bytevector_some (port)
1287 Read from @var{port}, blocking as necessary, until data are available or
1288 and end-of-file is reached. Return either a new bytevector containing
1289 the data read or the end-of-file object.
1292 @deffn {Scheme Procedure} get-bytevector-all port
1293 @deffnx {C Function} scm_get_bytevector_all (port)
1294 Read from @var{port}, blocking as necessary, until the end-of-file is
1295 reached. Return either a new bytevector containing the data read or the
1296 end-of-file object (if no data were available).
1299 @node R6RS Binary Output
1300 @subsubsection Binary Output
1302 Binary output ports can be created with the procedures below.
1304 @deffn {Scheme Procedure} open-bytevector-output-port [transcoder]
1305 @deffnx {C Function} scm_open_bytevector_output_port (transcoder)
1306 Return two values: a binary output port and a procedure. The latter
1307 should be called with zero arguments to obtain a bytevector containing
1308 the data accumulated by the port, as illustrated below.
1313 (open-bytevector-output-port))
1314 (lambda (port get-bytevector)
1315 (display "hello" port)
1318 @result{} #vu8(104 101 108 108 111)
1321 @c FIXME: Update description when implemented.
1322 The @var{transcoder} argument is currently not supported.
1325 @cindex custom binary output ports
1327 @deffn {Scheme Procedure} make-custom-binary-output-port id write! get-position set-position! close
1328 @deffnx {C Function} scm_make_custom_binary_output_port (id, write!, get-position, set-position!, close)
1329 Return a new custom binary output port named @var{id} (a string) whose
1330 output is sunk by invoking @var{write!} and passing it a bytevector, an
1331 index where bytes should be read from this bytevector, and the number of
1332 bytes to be ``written''. The @code{write!} procedure must return an
1333 integer indicating the number of bytes actually written; when it is
1334 passed @code{0} as the number of bytes to write, it should behave as
1335 though an end-of-file was sent to the byte sink.
1337 The other arguments are as for @code{make-custom-binary-input-port}
1338 (@pxref{R6RS Binary Input, @code{make-custom-binary-input-port}}).
1341 @cindex binary output
1342 Writing to a binary output port can be done using the following
1345 @deffn {Scheme Procedure} put-u8 port octet
1346 @deffnx {C Function} scm_put_u8 (port, octet)
1347 Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
1351 @deffn {Scheme Procedure} put-bytevector port bv [start [count]]
1352 @deffnx {C Function} scm_put_bytevector (port, bv, start, count)
1353 Write the contents of @var{bv} to @var{port}, optionally starting at
1354 index @var{start} and limiting to @var{count} octets.
1358 @node I/O Extensions
1359 @subsection Using and Extending Ports in C
1362 * C Port Interface:: Using ports from C.
1363 * Port Implementation:: How to implement a new port type in C.
1367 @node C Port Interface
1368 @subsubsection C Port Interface
1369 @cindex C port interface
1370 @cindex Port, C interface
1372 This section describes how to use Scheme ports from C.
1374 @subsubheading Port basics
1377 @tindex scm_ptob_descriptor
1379 @findex SCM_PTAB_ENTRY
1382 There are two main data structures. A port type object (ptob) is of
1383 type @code{scm_ptob_descriptor}. A port instance is of type
1384 @code{scm_port}. Given an @code{SCM} variable which points to a port,
1385 the corresponding C port object can be obtained using the
1386 @code{SCM_PTAB_ENTRY} macro. The ptob can be obtained by using
1387 @code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs}
1390 @subsubheading Port buffers
1392 An input port always has a read buffer and an output port always has a
1393 write buffer. However the size of these buffers is not guaranteed to be
1394 more than one byte (e.g., the @code{shortbuf} field in @code{scm_port}
1395 which is used when no other buffer is allocated). The way in which the
1396 buffers are allocated depends on the implementation of the ptob. For
1397 example in the case of an fport, buffers may be allocated with malloc
1398 when the port is created, but in the case of an strport the underlying
1399 string is used as the buffer.
1401 @subsubheading The @code{rw_random} flag
1403 Special treatment is required for ports which can be seeked at random.
1404 Before various operations, such as seeking the port or changing from
1405 input to output on a bidirectional port or vice versa, the port
1406 implementation must be given a chance to update its state. The write
1407 buffer is updated by calling the @code{flush} ptob procedure and the
1408 input buffer is updated by calling the @code{end_input} ptob procedure.
1409 In the case of an fport, @code{flush} causes buffered output to be
1410 written to the file descriptor, while @code{end_input} causes the
1411 descriptor position to be adjusted to account for buffered input which
1414 The special treatment must be performed if the @code{rw_random} flag in
1415 the port is non-zero.
1417 @subsubheading The @code{rw_active} variable
1419 The @code{rw_active} variable in the port is only used if
1420 @code{rw_random} is set. It's defined as an enum with the following
1425 the read buffer may have unread data.
1427 @item SCM_PORT_WRITE
1428 the write buffer may have unwritten data.
1430 @item SCM_PORT_NEITHER
1431 neither the write nor the read buffer has data.
1434 @subsubheading Reading from a port.
1436 To read from a port, it's possible to either call existing libguile
1437 procedures such as @code{scm_getc} and @code{scm_read_line} or to read
1438 data from the read buffer directly. Reading from the buffer involves
1439 the following steps:
1443 Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}.
1446 Fill the read buffer, if it's empty, using @code{scm_fill_input}.
1448 @item Read the data from the buffer and update the read position in
1449 the buffer. Steps 2) and 3) may be repeated as many times as required.
1451 @item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set.
1453 @item update the port's line and column counts.
1456 @subsubheading Writing to a port.
1458 To write data to a port, calling @code{scm_lfwrite} should be sufficient for
1459 most purposes. This takes care of the following steps:
1463 End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}.
1466 Pass the data to the ptob implementation using the @code{write} ptob
1467 procedure. The advantage of using the ptob @code{write} instead of
1468 manipulating the write buffer directly is that it allows the data to be
1469 written in one operation even if the port is using the single-byte
1473 Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random}
1478 @node Port Implementation
1479 @subsubsection Port Implementation
1480 @cindex Port implementation
1482 This section describes how to implement a new port type in C.
1484 As described in the previous section, a port type object (ptob) is
1485 a structure of type @code{scm_ptob_descriptor}. A ptob is created by
1486 calling @code{scm_make_port_type}.
1488 @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))
1489 Return a new port type object. The @var{name}, @var{fill_input} and
1490 @var{write} parameters are initial values for those port type fields,
1491 as described below. The other fields are initialized with default
1492 values and can be changed later.
1495 All of the elements of the ptob, apart from @code{name}, are procedures
1496 which collectively implement the port behaviour. Creating a new port
1497 type mostly involves writing these procedures.
1501 A pointer to a NUL terminated string: the name of the port type. This
1502 is the only element of @code{scm_ptob_descriptor} which is not
1503 a procedure. Set via the first argument to @code{scm_make_port_type}.
1506 Called during garbage collection to mark any SCM objects that a port
1507 object may contain. It doesn't need to be set unless the port has
1508 @code{SCM} components. Set using
1510 @deftypefun void scm_set_port_mark (scm_t_bits tc, SCM (*mark) (SCM port))
1514 Called when the port is collected during gc. It
1515 should free any resources used by the port.
1518 @deftypefun void scm_set_port_free (scm_t_bits tc, size_t (*free) (SCM port))
1522 Called when @code{write} is called on the port object, to print a
1523 port description. E.g., for an fport it may produce something like:
1524 @code{#<input: /etc/passwd 3>}. Set using
1526 @deftypefun void scm_set_port_print (scm_t_bits tc, int (*print) (SCM port, SCM dest_port, scm_print_state *pstate))
1527 The first argument @var{port} is the object being printed, the second
1528 argument @var{dest_port} is where its description should go.
1532 Not used at present. Set using
1534 @deftypefun void scm_set_port_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM))
1538 Called when the port is closed, unless it was collected during gc. It
1539 should free any resources used by the port.
1542 @deftypefun void scm_set_port_close (scm_t_bits tc, int (*close) (SCM port))
1546 Accept data which is to be written using the port. The port implementation
1547 may choose to buffer the data instead of processing it directly.
1548 Set via the third argument to @code{scm_make_port_type}.
1551 Complete the processing of buffered output data. Reset the value of
1552 @code{rw_active} to @code{SCM_PORT_NEITHER}.
1555 @deftypefun void scm_set_port_flush (scm_t_bits tc, void (*flush) (SCM port))
1559 Perform any synchronization required when switching from input to output
1560 on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}.
1563 @deftypefun void scm_set_port_end_input (scm_t_bits tc, void (*end_input) (SCM port, int offset))
1567 Read new data into the read buffer and return the first character. It
1568 can be assumed that the read buffer is empty when this procedure is called.
1569 Set via the second argument to @code{scm_make_port_type}.
1572 Return a lower bound on the number of bytes that could be read from the
1573 port without blocking. It can be assumed that the current state of
1574 @code{rw_active} is @code{SCM_PORT_NEITHER}.
1577 @deftypefun void scm_set_port_input_waiting (scm_t_bits tc, int (*input_waiting) (SCM port))
1581 Set the current position of the port. The procedure can not make
1582 any assumptions about the value of @code{rw_active} when it's
1583 called. It can reset the buffers first if desired by using something
1587 if (pt->rw_active == SCM_PORT_READ)
1588 scm_end_input (port);
1589 else if (pt->rw_active == SCM_PORT_WRITE)
1593 However note that this will have the side effect of discarding any data
1594 in the unread-char buffer, in addition to any side effects from the
1595 @code{end_input} and @code{flush} ptob procedures. This is undesirable
1596 when seek is called to measure the current position of the port, i.e.,
1597 @code{(seek p 0 SEEK_CUR)}. The libguile fport and string port
1598 implementations take care to avoid this problem.
1600 The procedure is set using
1602 @deftypefun void scm_set_port_seek (scm_t_bits tc, scm_t_off (*seek) (SCM port, scm_t_off offset, int whence))
1606 Truncate the port data to be specified length. It can be assumed that the
1607 current state of @code{rw_active} is @code{SCM_PORT_NEITHER}.
1610 @deftypefun void scm_set_port_truncate (scm_t_bits tc, void (*truncate) (SCM port, scm_t_off length))
1617 @c TeX-master: "guile.texi"