3 @chapter Input and Output
6 * Ports:: The idea of the port abstraction.
7 * Reading:: Procedures for reading from a port.
8 * Writing:: Procedures for writing to a port.
9 * Closing:: Procedures to close a port.
10 * Random Access:: Moving around a random access port.
11 * Line/Delimited:: Read and write lines or delimited text.
12 * Block Reading and Writing:: Reading and writing blocks of text.
13 * Default Ports:: Defaults for input, output and errors.
14 * Port Types:: Types of port and how to make them.
15 * I/O Extensions:: Using and extending ports in C.
22 Sequential input/output in Scheme is represented by operations on a
23 @dfn{port}. This chapter explains the operations that Guile provides
24 for working with ports.
26 Ports are created by opening, for instance @code{open-file} for a file
27 (@pxref{File Ports}). Characters can be read from an input port and
28 written to an output port, or both on an input/output port. A port
29 can be closed (@pxref{Closing}) when no longer required, after which
30 any attempt to read or write is an error.
32 The formal definition of a port is very generic: an input port is
33 simply ``an object which can deliver characters on demand,'' and an
34 output port is ``an object which can accept characters.'' Because
35 this definition is so loose, it is easy to write functions that
36 simulate ports in software. @dfn{Soft ports} and @dfn{string ports}
37 are two interesting and powerful examples of this technique.
38 (@pxref{Soft Ports}, and @ref{String Ports}.)
40 Ports are garbage collected in the usual way (@pxref{Memory
41 Management}), and will be closed at that time if not already closed.
42 In this case any errors occuring in the close will not be reported.
43 Usually a program will want to explicitly close so as to be sure all
44 its operations have been successful. Of course if a program has
45 abandoned something due to an error or other condition then closing
46 problems are probably not of interest.
48 It is strongly recommended that file ports be closed explicitly when
49 no longer required. Most systems have limits on how many files can be
50 open, both on a per-process and a system-wide basis. A program that
51 uses many files should take care not to hit those limits. The same
52 applies to similar system resources such as pipes and sockets.
54 Note that automatic garbage collection is triggered only by memory
55 consumption, not by file or other resource usage, so a program cannot
56 rely on that to keep it away from system limits. An explicit call to
57 @code{gc} can of course be relied on to pick up unreferenced ports.
58 If program flow makes it hard to be certain when to close then this
59 may be an acceptable way to control resource usage.
62 @deffn {Scheme Procedure} input-port? x
63 @deffnx {C Function} scm_input_port_p (x)
64 Return @code{#t} if @var{x} is an input port, otherwise return
65 @code{#f}. Any object satisfying this predicate also satisfies
70 @deffn {Scheme Procedure} output-port? x
71 @deffnx {C Function} scm_output_port_p (x)
72 Return @code{#t} if @var{x} is an output port, otherwise return
73 @code{#f}. Any object satisfying this predicate also satisfies
77 @deffn {Scheme Procedure} port? x
78 @deffnx {C Function} scm_port_p (x)
79 Return a boolean indicating whether @var{x} is a port.
80 Equivalent to @code{(or (input-port? @var{x}) (output-port?
88 [Generic procedures for reading from ports.]
91 @deffn {Scheme Procedure} eof-object? x
92 @deffnx {C Function} scm_eof_object_p (x)
93 Return @code{#t} if @var{x} is an end-of-file object; otherwise
98 @deffn {Scheme Procedure} char-ready? [port]
99 @deffnx {C Function} scm_char_ready_p (port)
100 Return @code{#t} if a character is ready on input @var{port}
101 and return @code{#f} otherwise. If @code{char-ready?} returns
102 @code{#t} then the next @code{read-char} operation on
103 @var{port} is guaranteed not to hang. If @var{port} is a file
104 port at end of file then @code{char-ready?} returns @code{#t}.
105 @footnote{@code{char-ready?} exists to make it possible for a
106 program to accept characters from interactive ports without
107 getting stuck waiting for input. Any input editors associated
108 with such ports must make sure that characters whose existence
109 has been asserted by @code{char-ready?} cannot be rubbed out.
110 If @code{char-ready?} were to return @code{#f} at end of file,
111 a port at end of file would be indistinguishable from an
112 interactive port that has no ready characters.}
116 @deffn {Scheme Procedure} read-char [port]
117 @deffnx {C Function} scm_read_char (port)
118 Return the next character available from @var{port}, updating
119 @var{port} to point to the following character. If no more
120 characters are available, the end-of-file object is returned.
123 @deftypefn {C Function} size_t scm_c_read (SCM port, void *buffer, size_t size)
124 Read up to @var{size} bytes from @var{port} and store them in
125 @var{buffer}. The return value is the number of bytes actually read,
126 which can be less than @var{size} if end-of-file has been reached.
128 Note that this function does not update @code{port-line} and
129 @code{port-column} below.
133 @deffn {Scheme Procedure} peek-char [port]
134 @deffnx {C Function} scm_peek_char (port)
135 Return the next character available from @var{port},
136 @emph{without} updating @var{port} to point to the following
137 character. If no more characters are available, the
138 end-of-file object is returned.@footnote{The value returned by
139 a call to @code{peek-char} is the same as the value that would
140 have been returned by a call to @code{read-char} on the same
141 port. The only difference is that the very next call to
142 @code{read-char} or @code{peek-char} on that @var{port} will
143 return the value returned by the preceding call to
144 @code{peek-char}. In particular, a call to @code{peek-char} on
145 an interactive port will hang waiting for input whenever a call
146 to @code{read-char} would have hung.}
149 @deffn {Scheme Procedure} unread-char cobj [port]
150 @deffnx {C Function} scm_unread_char (cobj, port)
151 Place @var{char} in @var{port} so that it will be read by the
152 next read operation. If called multiple times, the unread characters
153 will be read again in last-in first-out order. If @var{port} is
154 not supplied, the current input port is used.
157 @deffn {Scheme Procedure} unread-string str port
158 @deffnx {C Function} scm_unread_string (str, port)
159 Place the string @var{str} in @var{port} so that its characters will
160 be read from left-to-right as the next characters from @var{port}
161 during subsequent read operations. If called multiple times, the
162 unread characters will be read again in last-in first-out order. If
163 @var{port} is not supplied, the current-input-port is used.
166 @deffn {Scheme Procedure} drain-input port
167 @deffnx {C Function} scm_drain_input (port)
168 This procedure clears a port's input buffers, similar
169 to the way that force-output clears the output buffer. The
170 contents of the buffers are returned as a single string, e.g.,
173 (define p (open-input-file ...))
174 (drain-input p) => empty string, nothing buffered yet.
175 (unread-char (read-char p) p)
176 (drain-input p) => initial chars from p, up to the buffer size.
179 Draining the buffers may be useful for cleanly finishing
180 buffered I/O so that the file descriptor can be used directly
184 @deffn {Scheme Procedure} port-column port
185 @deffnx {Scheme Procedure} port-line port
186 @deffnx {C Function} scm_port_column (port)
187 @deffnx {C Function} scm_port_line (port)
188 Return the current column number or line number of @var{port}.
190 unknown, the result is #f. Otherwise, the result is a 0-origin integer
191 - i.e.@: the first character of the first line is line 0, column 0.
192 (However, when you display a file position, for example in an error
193 message, we recommend you add 1 to get 1-origin integers. This is
194 because lines and column numbers traditionally start with 1, and that is
195 what non-programmers will find most natural.)
198 @deffn {Scheme Procedure} set-port-column! port column
199 @deffnx {Scheme Procedure} set-port-line! port line
200 @deffnx {C Function} scm_set_port_column_x (port, column)
201 @deffnx {C Function} scm_set_port_line_x (port, line)
202 Set the current column or line number of @var{port}.
208 [Generic procedures for writing to ports.]
210 @deffn {Scheme Procedure} get-print-state port
211 @deffnx {C Function} scm_get_print_state (port)
212 Return the print state of the port @var{port}. If @var{port}
213 has no associated print state, @code{#f} is returned.
217 @deffn {Scheme Procedure} write obj [port]
218 Send a representation of @var{obj} to @var{port} or to the current
219 output port if not given.
221 The output is designed to be machine readable, and can be read back
222 with @code{read} (@pxref{Reading}). Strings are printed in
223 doublequotes, with escapes if necessary, and characters are printed in
228 @deffn {Scheme Procedure} display obj [port]
229 Send a representation of @var{obj} to @var{port} or to the current
230 output port if not given.
232 The output is designed for human readability, it differs from
233 @code{write} in that strings are printed without doublequotes and
234 escapes, and characters are printed as per @code{write-char}, not in
239 @deffn {Scheme Procedure} newline [port]
240 @deffnx {C Function} scm_newline (port)
241 Send a newline to @var{port}.
242 If @var{port} is omitted, send to the current output port.
245 @deffn {Scheme Procedure} port-with-print-state port pstate
246 @deffnx {C Function} scm_port_with_print_state (port, pstate)
247 Create a new port which behaves like @var{port}, but with an
248 included print state @var{pstate}.
251 @deffn {Scheme Procedure} print-options-interface [setting]
252 @deffnx {C Function} scm_print_options (setting)
253 Option interface for the print options. Instead of using
254 this procedure directly, use the procedures
255 @code{print-enable}, @code{print-disable}, @code{print-set!}
256 and @code{print-options}.
259 @deffn {Scheme Procedure} simple-format destination message . args
260 @deffnx {C Function} scm_simple_format (destination, message, args)
261 Write @var{message} to @var{destination}, defaulting to
262 the current output port.
263 @var{message} can contain @code{~A} (was @code{%s}) and
264 @code{~S} (was @code{%S}) escapes. When printed,
265 the escapes are replaced with corresponding members of
267 @code{~A} formats using @code{display} and @code{~S} formats
269 If @var{destination} is @code{#t}, then use the current output
270 port, if @var{destination} is @code{#f}, then return a string
271 containing the formatted text. Does not add a trailing newline.
275 @deffn {Scheme Procedure} write-char chr [port]
276 @deffnx {C Function} scm_write_char (chr, port)
277 Send character @var{chr} to @var{port}.
280 @deftypefn {C Function} void scm_c_write (SCM port, const void *buffer, size_t size)
281 Write @var{size} bytes at @var{buffer} to @var{port}.
283 Note that this function does not update @code{port-line} and
284 @code{port-column} (@pxref{Reading}).
288 @deffn {Scheme Procedure} force-output [port]
289 @deffnx {C Function} scm_force_output (port)
290 Flush the specified output port, or the current output port if @var{port}
291 is omitted. The current output buffer contents are passed to the
292 underlying port implementation (e.g., in the case of fports, the
293 data will be written to the file and the output buffer will be cleared.)
294 It has no effect on an unbuffered port.
296 The return value is unspecified.
299 @deffn {Scheme Procedure} flush-all-ports
300 @deffnx {C Function} scm_flush_all_ports ()
301 Equivalent to calling @code{force-output} on
302 all open output ports. The return value is unspecified.
309 @deffn {Scheme Procedure} close-port port
310 @deffnx {C Function} scm_close_port (port)
311 Close the specified port object. Return @code{#t} if it
312 successfully closes a port or @code{#f} if it was already
313 closed. An exception may be raised if an error occurs, for
314 example when flushing buffered output. See also @ref{Ports and
315 File Descriptors, close}, for a procedure which can close file
319 @deffn {Scheme Procedure} close-input-port port
320 @deffnx {Scheme Procedure} close-output-port port
321 @deffnx {C Function} scm_close_input_port (port)
322 @deffnx {C Function} scm_close_output_port (port)
323 @rnindex close-input-port
324 @rnindex close-output-port
325 Close the specified input or output @var{port}. An exception may be
326 raised if an error occurs while closing. If @var{port} is already
327 closed, nothing is done. The return value is unspecified.
329 See also @ref{Ports and File Descriptors, close}, for a procedure
330 which can close file descriptors.
333 @deffn {Scheme Procedure} port-closed? port
334 @deffnx {C Function} scm_port_closed_p (port)
335 Return @code{#t} if @var{port} is closed or @code{#f} if it is
341 @section Random Access
343 @deffn {Scheme Procedure} seek fd_port offset whence
344 @deffnx {C Function} scm_seek (fd_port, offset, whence)
345 Sets the current position of @var{fd/port} to the integer
346 @var{offset}, which is interpreted according to the value of
349 One of the following variables should be supplied for
352 Seek from the beginning of the file.
355 Seek from the current position.
358 Seek from the end of the file.
360 If @var{fd/port} is a file descriptor, the underlying system
361 call is @code{lseek}. @var{port} may be a string port.
363 The value returned is the new position in the file. This means
364 that the current position of a port can be obtained using:
366 (seek port 0 SEEK_CUR)
370 @deffn {Scheme Procedure} ftell fd_port
371 @deffnx {C Function} scm_ftell (fd_port)
372 Return an integer representing the current position of
373 @var{fd/port}, measured from the beginning. Equivalent to:
376 (seek port 0 SEEK_CUR)
382 @deffn {Scheme Procedure} truncate-file object [length]
383 @deffnx {C Function} scm_truncate_file (object, length)
384 Truncates the object referred to by @var{object} to at most
385 @var{length} bytes. @var{object} can be a string containing a
386 file name or an integer file descriptor or a port.
387 @var{length} may be omitted if @var{object} is not a file name,
388 in which case the truncation occurs at the current port.
389 position. The return value is unspecified.
393 @section Line Oriented and Delimited Text
395 The delimited-I/O module can be accessed with:
398 (use-modules (ice-9 rdelim))
401 It can be used to read or write lines of text, or read text delimited by
402 a specified set of characters. It's similar to the @code{(scsh rdelim)}
403 module from guile-scsh, but does not use multiple values or character
404 sets and has an extra procedure @code{write-line}.
406 @c begin (scm-doc-string "rdelim.scm" "read-line")
407 @deffn {Scheme Procedure} read-line [port] [handle-delim]
408 Return a line of text from @var{port} if specified, otherwise from the
409 value returned by @code{(current-input-port)}. Under Unix, a line of text
410 is terminated by the first end-of-line character or by end-of-file.
412 If @var{handle-delim} is specified, it should be one of the following
416 Discard the terminating delimiter. This is the default, but it will
417 be impossible to tell whether the read terminated with a delimiter or
420 Append the terminating delimiter (if any) to the returned string.
422 Push the terminating delimiter (if any) back on to the port.
424 Return a pair containing the string read from the port and the
425 terminating delimiter or end-of-file object.
429 @c begin (scm-doc-string "rdelim.scm" "read-line!")
430 @deffn {Scheme Procedure} read-line! buf [port]
431 Read a line of text into the supplied string @var{buf} and return the
432 number of characters added to @var{buf}. If @var{buf} is filled, then
433 @code{#f} is returned.
434 Read from @var{port} if
435 specified, otherwise from the value returned by @code{(current-input-port)}.
438 @c begin (scm-doc-string "rdelim.scm" "read-delimited")
439 @deffn {Scheme Procedure} read-delimited delims [port] [handle-delim]
440 Read text until one of the characters in the string @var{delims} is found
441 or end-of-file is reached. Read from @var{port} if supplied, otherwise
442 from the value returned by @code{(current-input-port)}.
443 @var{handle-delim} takes the same values as described for @code{read-line}.
446 @c begin (scm-doc-string "rdelim.scm" "read-delimited!")
447 @deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end]
448 Read text into the supplied string @var{buf} and return the number of
449 characters added to @var{buf} (subject to @var{handle-delim}, which takes
450 the same values specified for @code{read-line}. If @var{buf} is filled,
451 @code{#f} is returned for both the number of characters read and the
452 delimiter. Also terminates if one of the characters in the string
453 @var{delims} is found
454 or end-of-file is reached. Read from @var{port} if supplied, otherwise
455 from the value returned by @code{(current-input-port)}.
458 @deffn {Scheme Procedure} write-line obj [port]
459 @deffnx {C Function} scm_write_line (obj, port)
460 Display @var{obj} and a newline character to @var{port}. If
461 @var{port} is not specified, @code{(current-output-port)} is
462 used. This function is equivalent to:
469 Some of the abovementioned I/O functions rely on the following C
470 primitives. These will mainly be of interest to people hacking Guile
473 @deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]]
474 @deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end)
475 Read characters from @var{port} into @var{str} until one of the
476 characters in the @var{delims} string is encountered. If
477 @var{gobble} is true, discard the delimiter character;
478 otherwise, leave it in the input stream for the next read. If
479 @var{port} is not specified, use the value of
480 @code{(current-input-port)}. If @var{start} or @var{end} are
481 specified, store data only into the substring of @var{str}
482 bounded by @var{start} and @var{end} (which default to the
483 beginning and end of the string, respectively).
485 Return a pair consisting of the delimiter that terminated the
486 string and the number of characters read. If reading stopped
487 at the end of file, the delimiter returned is the
488 @var{eof-object}; if the string was filled without encountering
489 a delimiter, this value is @code{#f}.
492 @deffn {Scheme Procedure} %read-line [port]
493 @deffnx {C Function} scm_read_line (port)
494 Read a newline-terminated line from @var{port}, allocating storage as
495 necessary. The newline terminator (if any) is removed from the string,
496 and a pair consisting of the line and its delimiter is returned. The
497 delimiter may be either a newline or the @var{eof-object}; if
498 @code{%read-line} is called at the end of file, it returns the pair
499 @code{(#<eof> . #<eof>)}.
502 @node Block Reading and Writing
503 @section Block reading and writing
505 The Block-string-I/O module can be accessed with:
508 (use-modules (ice-9 rw))
511 It currently contains procedures that help to implement the
512 @code{(scsh rw)} module in guile-scsh.
514 @deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]]
515 @deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end)
516 Read characters from a port or file descriptor into a
517 string @var{str}. A port must have an underlying file
518 descriptor --- a so-called fport. This procedure is
519 scsh-compatible and can efficiently read large strings.
524 attempt to fill the entire string, unless the @var{start}
525 and/or @var{end} arguments are supplied. i.e., @var{start}
526 defaults to 0 and @var{end} defaults to
527 @code{(string-length str)}
529 use the current input port if @var{port_or_fdes} is not
532 return fewer than the requested number of characters in some
533 cases, e.g., on end of file, if interrupted by a signal, or if
534 not all the characters are immediately available.
536 wait indefinitely for some input if no characters are
538 unless the port is in non-blocking mode.
540 read characters from the port's input buffers if available,
541 instead from the underlying file descriptor.
543 return @code{#f} if end-of-file is encountered before reading
544 any characters, otherwise return the number of characters
547 return 0 if the port is in non-blocking mode and no characters
548 are immediately available.
550 return 0 if the request is for 0 bytes, with no
555 @deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]]
556 @deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end)
557 Write characters from a string @var{str} to a port or file
558 descriptor. A port must have an underlying file descriptor
559 --- a so-called fport. This procedure is
560 scsh-compatible and can efficiently write large strings.
565 attempt to write the entire string, unless the @var{start}
566 and/or @var{end} arguments are supplied. i.e., @var{start}
567 defaults to 0 and @var{end} defaults to
568 @code{(string-length str)}
570 use the current output port if @var{port_of_fdes} is not
573 in the case of a buffered port, store the characters in the
574 port's output buffer, if all will fit. If they will not fit
575 then any existing buffered characters will be flushed
577 to write the new characters directly to the underlying file
578 descriptor. If the port is in non-blocking mode and
579 buffered characters can not be flushed immediately, then an
580 @code{EAGAIN} system-error exception will be raised (Note:
581 scsh does not support the use of non-blocking buffered ports.)
583 write fewer than the requested number of
584 characters in some cases, e.g., if interrupted by a signal or
585 if not all of the output can be accepted immediately.
587 wait indefinitely for at least one character
588 from @var{str} to be accepted by the port, unless the port is
589 in non-blocking mode.
591 return the number of characters accepted by the port.
593 return 0 if the port is in non-blocking mode and can not accept
594 at least one character from @var{str} immediately
596 return 0 immediately if the request size is 0 bytes.
601 @section Default Ports for Input, Output and Errors
603 @rnindex current-input-port
604 @deffn {Scheme Procedure} current-input-port
605 @deffnx {C Function} scm_current_input_port ()
606 Return the current input port. This is the default port used
607 by many input procedures. Initially, @code{current-input-port}
608 returns the @dfn{standard input} in Unix and C terminology.
611 @rnindex current-output-port
612 @deffn {Scheme Procedure} current-output-port
613 @deffnx {C Function} scm_current_output_port ()
614 Return the current output port. This is the default port used
615 by many output procedures. Initially,
616 @code{current-output-port} returns the @dfn{standard output} in
617 Unix and C terminology.
620 @deffn {Scheme Procedure} current-error-port
621 @deffnx {C Function} scm_current_error_port ()
622 Return the port to which errors and warnings should be sent (the
623 @dfn{standard error} in Unix and C terminology).
626 @deffn {Scheme Procedure} set-current-input-port port
627 @deffnx {Scheme Procedure} set-current-output-port port
628 @deffnx {Scheme Procedure} set-current-error-port port
629 @deffnx {C Function} scm_set_current_input_port (port)
630 @deffnx {C Function} scm_set_current_output_port (port)
631 @deffnx {C Function} scm_set_current_error_port (port)
632 Change the ports returned by @code{current-input-port},
633 @code{current-output-port} and @code{current-error-port}, respectively,
634 so that they use the supplied @var{port} for input or output.
639 @section Types of Port
641 [Types of port; how to make them.]
644 * File Ports:: Ports on an operating system file.
645 * String Ports:: Ports on a Scheme string.
646 * Soft Ports:: Ports on arbitrary Scheme procedures.
647 * Void Ports:: Ports on nothing at all.
652 @subsection File Ports
654 The following procedures are used to open file ports.
655 See also @ref{Ports and File Descriptors, open}, for an interface
656 to the Unix @code{open} system call.
658 Most systems have limits on how many files can be open, so it's
659 strongly recommended that file ports be closed explicitly when no
660 longer required (@pxref{Ports}).
662 @deffn {Scheme Procedure} open-file filename mode
663 @deffnx {C Function} scm_open_file (filename, mode)
664 Open the file whose name is @var{filename}, and return a port
665 representing that file. The attributes of the port are
666 determined by the @var{mode} string. The way in which this is
667 interpreted is similar to C stdio. The first character must be
668 one of the following:
671 Open an existing file for input.
673 Open a file for output, creating it if it doesn't already exist
674 or removing its contents if it does.
676 Open a file for output, creating it if it doesn't already
677 exist. All writes to the port will go to the end of the file.
678 The "append mode" can be turned off while the port is in use
679 @pxref{Ports and File Descriptors, fcntl}
681 The following additional characters can be appended:
684 Open the port for both input and output. E.g., @code{r+}: open
685 an existing file for both input and output.
687 Create an "unbuffered" port. In this case input and output
688 operations are passed directly to the underlying port
689 implementation without additional buffering. This is likely to
690 slow down I/O operations. The buffering mode can be changed
691 while a port is in use @pxref{Ports and File Descriptors,
694 Add line-buffering to the port. The port output buffer will be
695 automatically flushed whenever a newline character is written.
697 In theory we could create read/write ports which were buffered
698 in one direction only. However this isn't included in the
699 current interfaces. If a file cannot be opened with the access
700 requested, @code{open-file} throws an exception.
703 @rnindex open-input-file
704 @deffn {Scheme Procedure} open-input-file filename
705 Open @var{filename} for input. Equivalent to
707 (open-file @var{filename} "r")
711 @rnindex open-output-file
712 @deffn {Scheme Procedure} open-output-file filename
713 Open @var{filename} for output. Equivalent to
715 (open-file @var{filename} "w")
719 @deffn {Scheme Procedure} call-with-input-file filename proc
720 @deffnx {Scheme Procedure} call-with-output-file filename proc
721 @rnindex call-with-input-file
722 @rnindex call-with-output-file
723 Open @var{filename} for input or output, and call @code{(@var{proc}
724 port)} with the resulting port. Return the value returned by
725 @var{proc}. @var{filename} is opened as per @code{open-input-file} or
726 @code{open-output-file} respectively, and an error is signalled if it
729 When @var{proc} returns, the port is closed. If @var{proc} does not
730 return (eg.@: if it throws an error), then the port might not be
731 closed automatically, though it will be garbage collected in the usual
732 way if not otherwise referenced.
735 @deffn {Scheme Procedure} with-input-from-file filename thunk
736 @deffnx {Scheme Procedure} with-output-to-file filename thunk
737 @deffnx {Scheme Procedure} with-error-to-file filename thunk
738 @rnindex with-input-from-file
739 @rnindex with-output-to-file
740 Open @var{filename} and call @code{(@var{thunk})} with the new port
741 setup as respectively the @code{current-input-port},
742 @code{current-output-port}, or @code{current-error-port}. Return the
743 value returned by @var{thunk}. @var{filename} is opened as per
744 @code{open-input-file} or @code{open-output-file} respectively, and an
745 error is signalled if it cannot be opened.
747 When @var{thunk} returns, the port is closed and the previous setting
748 of the respective current port is restored.
750 The current port setting is managed with @code{dynamic-wind}, so the
751 previous value is restored no matter how @var{thunk} exits (eg.@: an
752 exception), and if @var{thunk} is re-entered (via a captured
753 continuation) then it's set again to the @var{FILENAME} port.
755 The port is closed when @var{thunk} returns normally, but not when
756 exited via an exception or new continuation. This ensures it's still
757 ready for use if @var{thunk} is re-entered by a captured continuation.
758 Of course the port is always garbage collected and closed in the usual
759 way when no longer referenced anywhere.
762 @deffn {Scheme Procedure} port-mode port
763 @deffnx {C Function} scm_port_mode (port)
764 Return the port modes associated with the open port @var{port}.
765 These will not necessarily be identical to the modes used when
766 the port was opened, since modes such as "append" which are
767 used only during port creation are not retained.
770 @deffn {Scheme Procedure} port-filename port
771 @deffnx {C Function} scm_port_filename (port)
772 Return the filename associated with @var{port}. This function returns
773 the strings "standard input", "standard output" and "standard error"
774 when called on the current input, output and error ports respectively.
777 @deffn {Scheme Procedure} set-port-filename! port filename
778 @deffnx {C Function} scm_set_port_filename_x (port, filename)
779 Change the filename associated with @var{port}, using the current input
780 port if none is specified. Note that this does not change the port's
781 source of data, but only the value that is returned by
782 @code{port-filename} and reported in diagnostic output.
785 @deffn {Scheme Procedure} file-port? obj
786 @deffnx {C Function} scm_file_port_p (obj)
787 Determine whether @var{obj} is a port that is related to a file.
792 @subsection String Ports
794 The following allow string ports to be opened by analogy to R4R*
795 file port facilities:
797 @deffn {Scheme Procedure} call-with-output-string proc
798 @deffnx {C Function} scm_call_with_output_string (proc)
799 Calls the one-argument procedure @var{proc} with a newly created output
800 port. When the function returns, the string composed of the characters
801 written into the port is returned.
804 @deffn {Scheme Procedure} call-with-input-string string proc
805 @deffnx {C Function} scm_call_with_input_string (string, proc)
806 Calls the one-argument procedure @var{proc} with a newly
807 created input port from which @var{string}'s contents may be
808 read. The value yielded by the @var{proc} is returned.
811 @deffn {Scheme Procedure} with-output-to-string thunk
812 Calls the zero-argument procedure @var{thunk} with the current output
813 port set temporarily to a new string port. It returns a string
814 composed of the characters written to the current output.
817 @deffn {Scheme Procedure} with-input-from-string string thunk
818 Calls the zero-argument procedure @var{thunk} with the current input
819 port set temporarily to a string port opened on the specified
820 @var{string}. The value yielded by @var{thunk} is returned.
823 @deffn {Scheme Procedure} open-input-string str
824 @deffnx {C Function} scm_open_input_string (str)
825 Take a string and return an input port that delivers characters
826 from the string. The port can be closed by
827 @code{close-input-port}, though its storage will be reclaimed
828 by the garbage collector if it becomes inaccessible.
831 @deffn {Scheme Procedure} open-output-string
832 @deffnx {C Function} scm_open_output_string ()
833 Return an output port that will accumulate characters for
834 retrieval by @code{get-output-string}. The port can be closed
835 by the procedure @code{close-output-port}, though its storage
836 will be reclaimed by the garbage collector if it becomes
840 @deffn {Scheme Procedure} get-output-string port
841 @deffnx {C Function} scm_get_output_string (port)
842 Given an output port created by @code{open-output-string},
843 return a string consisting of the characters that have been
844 output to the port so far.
847 A string port can be used in many procedures which accept a port
848 but which are not dependent on implementation details of fports.
849 E.g., seeking and truncating will work on a string port,
850 but trying to extract the file descriptor number will fail.
854 @subsection Soft Ports
856 A @dfn{soft-port} is a port based on a vector of procedures capable of
857 accepting or delivering characters. It allows emulation of I/O ports.
859 @deffn {Scheme Procedure} make-soft-port pv modes
860 @deffnx {C Function} scm_make_soft_port (pv, modes)
861 Return a port capable of receiving or delivering characters as
862 specified by the @var{modes} string (@pxref{File Ports,
863 open-file}). @var{pv} must be a vector of length 5 or 6. Its
864 components are as follows:
868 procedure accepting one character for output
870 procedure accepting a string for output
872 thunk for flushing output
874 thunk for getting one character
876 thunk for closing port (not by garbage collection)
878 (if present and not @code{#f}) thunk for computing the number of
879 characters that can be read from the port without blocking.
882 For an output-only port only elements 0, 1, 2, and 4 need be
883 procedures. For an input-only port only elements 3 and 4 need
884 be procedures. Thunks 2 and 4 can instead be @code{#f} if
885 there is no useful operation for them to perform.
887 If thunk 3 returns @code{#f} or an @code{eof-object}
888 (@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
889 Scheme}) it indicates that the port has reached end-of-file.
893 (define stdout (current-output-port))
894 (define p (make-soft-port
896 (lambda (c) (write c stdout))
897 (lambda (s) (display s stdout))
898 (lambda () (display "." stdout))
899 (lambda () (char-upcase (read-char)))
900 (lambda () (display "@@" stdout)))
903 (write p p) @result{} #<input-output: soft 8081e20>
909 @subsection Void Ports
911 This kind of port causes any data to be discarded when written to, and
912 always returns the end-of-file object when read from.
914 @deffn {Scheme Procedure} %make-void-port mode
915 @deffnx {C Function} scm_sys_make_void_port (mode)
916 Create and return a new void port. A void port acts like
917 @file{/dev/null}. The @var{mode} argument
918 specifies the input/output modes for this port: see the
919 documentation for @code{open-file} in @ref{File Ports}.
924 @section Using and Extending Ports in C
927 * C Port Interface:: Using ports from C.
928 * Port Implementation:: How to implement a new port type in C.
932 @node C Port Interface
933 @subsection C Port Interface
935 This section describes how to use Scheme ports from C.
937 @subsubsection Port basics
939 There are two main data structures. A port type object (ptob) is of
940 type @code{scm_ptob_descriptor}. A port instance is of type
941 @code{scm_port}. Given an @code{SCM} variable which points to a port,
942 the corresponding C port object can be obtained using the
943 @code{SCM_PTAB_ENTRY} macro. The ptob can be obtained by using
944 @code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs}
947 @subsubsection Port buffers
949 An input port always has a read buffer and an output port always has a
950 write buffer. However the size of these buffers is not guaranteed to be
951 more than one byte (e.g., the @code{shortbuf} field in @code{scm_port}
952 which is used when no other buffer is allocated). The way in which the
953 buffers are allocated depends on the implementation of the ptob. For
954 example in the case of an fport, buffers may be allocated with malloc
955 when the port is created, but in the case of an strport the underlying
956 string is used as the buffer.
958 @subsubsection The @code{rw_random} flag
960 Special treatment is required for ports which can be seeked at random.
961 Before various operations, such as seeking the port or changing from
962 input to output on a bidirectional port or vice versa, the port
963 implementation must be given a chance to update its state. The write
964 buffer is updated by calling the @code{flush} ptob procedure and the
965 input buffer is updated by calling the @code{end_input} ptob procedure.
966 In the case of an fport, @code{flush} causes buffered output to be
967 written to the file descriptor, while @code{end_input} causes the
968 descriptor position to be adjusted to account for buffered input which
971 The special treatment must be performed if the @code{rw_random} flag in
972 the port is non-zero.
974 @subsubsection The @code{rw_active} variable
976 The @code{rw_active} variable in the port is only used if
977 @code{rw_random} is set. It's defined as an enum with the following
982 the read buffer may have unread data.
985 the write buffer may have unwritten data.
987 @item SCM_PORT_NEITHER
988 neither the write nor the read buffer has data.
991 @subsubsection Reading from a port.
993 To read from a port, it's possible to either call existing libguile
994 procedures such as @code{scm_getc} and @code{scm_read_line} or to read
995 data from the read buffer directly. Reading from the buffer involves
1000 Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}.
1003 Fill the read buffer, if it's empty, using @code{scm_fill_input}.
1005 @item Read the data from the buffer and update the read position in
1006 the buffer. Steps 2) and 3) may be repeated as many times as required.
1008 @item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set.
1010 @item update the port's line and column counts.
1013 @subsubsection Writing to a port.
1015 To write data to a port, calling @code{scm_lfwrite} should be sufficient for
1016 most purposes. This takes care of the following steps:
1020 End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}.
1023 Pass the data to the ptob implementation using the @code{write} ptob
1024 procedure. The advantage of using the ptob @code{write} instead of
1025 manipulating the write buffer directly is that it allows the data to be
1026 written in one operation even if the port is using the single-byte
1030 Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random}
1035 @node Port Implementation
1036 @subsection Port Implementation
1038 This section describes how to implement a new port type in C.
1040 As described in the previous section, a port type object (ptob) is
1041 a structure of type @code{scm_ptob_descriptor}. A ptob is created by
1042 calling @code{scm_make_port_type}.
1044 All of the elements of the ptob, apart from @code{name}, are procedures
1045 which collectively implement the port behaviour. Creating a new port
1046 type mostly involves writing these procedures.
1048 @code{scm_make_port_type} initializes three elements of the structure
1049 (@code{name}, @code{fill_input} and @code{write}) from its arguments.
1050 The remaining elements are initialized with default values and can be
1051 set later if required.
1055 A pointer to a NUL terminated string: the name of the port type. This
1056 is the only element of @code{scm_ptob_descriptor} which is not
1057 a procedure. Set via the first argument to @code{scm_make_port_type}.
1060 Called during garbage collection to mark any SCM objects that a port
1061 object may contain. It doesn't need to be set unless the port has
1062 @code{SCM} components. Set using @code{scm_set_port_mark}.
1065 Called when the port is collected during gc. It
1066 should free any resources used by the port.
1067 Set using @code{scm_set_port_free}.
1070 Called when @code{write} is called on the port object, to print a
1071 port description. e.g., for an fport it may produce something like:
1072 @code{#<input: /etc/passwd 3>}. Set using @code{scm_set_port_print}.
1075 Not used at present. Set using @code{scm_set_port_equalp}.
1078 Called when the port is closed, unless it was collected during gc. It
1079 should free any resources used by the port.
1080 Set using @code{scm_set_port_close}.
1083 Accept data which is to be written using the port. The port implementation
1084 may choose to buffer the data instead of processing it directly.
1085 Set via the third argument to @code{scm_make_port_type}.
1088 Complete the processing of buffered output data. Reset the value of
1089 @code{rw_active} to @code{SCM_PORT_NEITHER}.
1090 Set using @code{scm_set_port_flush}.
1093 Perform any synchronization required when switching from input to output
1094 on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}.
1095 Set using @code{scm_set_port_end_input}.
1098 Read new data into the read buffer and return the first character. It
1099 can be assumed that the read buffer is empty when this procedure is called.
1100 Set via the second argument to @code{scm_make_port_type}.
1103 Return a lower bound on the number of bytes that could be read from the
1104 port without blocking. It can be assumed that the current state of
1105 @code{rw_active} is @code{SCM_PORT_NEITHER}.
1106 Set using @code{scm_set_port_input_waiting}.
1109 Set the current position of the port. The procedure can not make
1110 any assumptions about the value of @code{rw_active} when it's
1111 called. It can reset the buffers first if desired by using something
1115 if (pt->rw_active == SCM_PORT_READ)
1116 scm_end_input (object);
1117 else if (pt->rw_active == SCM_PORT_WRITE)
1118 ptob->flush (object);
1121 However note that this will have the side effect of discarding any data
1122 in the unread-char buffer, in addition to any side effects from the
1123 @code{end_input} and @code{flush} ptob procedures. This is undesirable
1124 when seek is called to measure the current position of the port, i.e.,
1125 @code{(seek p 0 SEEK_CUR)}. The libguile fport and string port
1126 implementations take care to avoid this problem.
1128 The procedure is set using @code{scm_set_port_seek}.
1131 Truncate the port data to be specified length. It can be assumed that the
1132 current state of @code{rw_active} is @code{SCM_PORT_NEITHER}.
1133 Set using @code{scm_set_port_truncate}.
1139 @c TeX-master: "guile.texi"