2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
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 * I/O Extensions:: Using and extending ports in C.
28 Sequential input/output in Scheme is represented by operations on a
29 @dfn{port}. This chapter explains the operations that Guile provides
30 for working with ports.
32 Ports are created by opening, for instance @code{open-file} for a file
33 (@pxref{File Ports}). Characters can be read from an input port and
34 written to an output port, or both on an input/output port. A port
35 can be closed (@pxref{Closing}) when no longer required, after which
36 any attempt to read or write is an error.
38 The formal definition of a port is very generic: an input port is
39 simply ``an object which can deliver characters on demand,'' and an
40 output port is ``an object which can accept characters.'' Because
41 this definition is so loose, it is easy to write functions that
42 simulate ports in software. @dfn{Soft ports} and @dfn{string ports}
43 are two interesting and powerful examples of this technique.
44 (@pxref{Soft Ports}, and @ref{String Ports}.)
46 Ports are garbage collected in the usual way (@pxref{Memory
47 Management}), and will be closed at that time if not already closed.
48 In this case any errors occuring in the close will not be reported.
49 Usually a program will want to explicitly close so as to be sure all
50 its operations have been successful. Of course if a program has
51 abandoned something due to an error or other condition then closing
52 problems are probably not of interest.
54 It is strongly recommended that file ports be closed explicitly when
55 no longer required. Most systems have limits on how many files can be
56 open, both on a per-process and a system-wide basis. A program that
57 uses many files should take care not to hit those limits. The same
58 applies to similar system resources such as pipes and sockets.
60 Note that automatic garbage collection is triggered only by memory
61 consumption, not by file or other resource usage, so a program cannot
62 rely on that to keep it away from system limits. An explicit call to
63 @code{gc} can of course be relied on to pick up unreferenced ports.
64 If program flow makes it hard to be certain when to close then this
65 may be an acceptable way to control resource usage.
68 @deffn {Scheme Procedure} input-port? x
69 @deffnx {C Function} scm_input_port_p (x)
70 Return @code{#t} if @var{x} is an input port, otherwise return
71 @code{#f}. Any object satisfying this predicate also satisfies
76 @deffn {Scheme Procedure} output-port? x
77 @deffnx {C Function} scm_output_port_p (x)
78 Return @code{#t} if @var{x} is an output port, otherwise return
79 @code{#f}. Any object satisfying this predicate also satisfies
83 @deffn {Scheme Procedure} port? x
84 @deffnx {C Function} scm_port_p (x)
85 Return a boolean indicating whether @var{x} is a port.
86 Equivalent to @code{(or (input-port? @var{x}) (output-port?
94 [Generic procedures for reading from ports.]
97 @deffn {Scheme Procedure} eof-object? x
98 @deffnx {C Function} scm_eof_object_p (x)
99 Return @code{#t} if @var{x} is an end-of-file object; otherwise
104 @deffn {Scheme Procedure} char-ready? [port]
105 @deffnx {C Function} scm_char_ready_p (port)
106 Return @code{#t} if a character is ready on input @var{port}
107 and return @code{#f} otherwise. If @code{char-ready?} returns
108 @code{#t} then the next @code{read-char} operation on
109 @var{port} is guaranteed not to hang. If @var{port} is a file
110 port at end of file then @code{char-ready?} returns @code{#t}.
111 @footnote{@code{char-ready?} exists to make it possible for a
112 program to accept characters from interactive ports without
113 getting stuck waiting for input. Any input editors associated
114 with such ports must make sure that characters whose existence
115 has been asserted by @code{char-ready?} cannot be rubbed out.
116 If @code{char-ready?} were to return @code{#f} at end of file,
117 a port at end of file would be indistinguishable from an
118 interactive port that has no ready characters.}
122 @deffn {Scheme Procedure} read-char [port]
123 @deffnx {C Function} scm_read_char (port)
124 Return the next character available from @var{port}, updating
125 @var{port} to point to the following character. If no more
126 characters are available, the end-of-file object is returned.
129 @deftypefn {C Function} size_t scm_c_read (SCM port, void *buffer, size_t size)
130 Read up to @var{size} bytes from @var{port} and store them in
131 @var{buffer}. The return value is the number of bytes actually read,
132 which can be less than @var{size} if end-of-file has been reached.
134 Note that this function does not update @code{port-line} and
135 @code{port-column} below.
139 @deffn {Scheme Procedure} peek-char [port]
140 @deffnx {C Function} scm_peek_char (port)
141 Return the next character available from @var{port},
142 @emph{without} updating @var{port} to point to the following
143 character. If no more characters are available, the
144 end-of-file object is returned.@footnote{The value returned by
145 a call to @code{peek-char} is the same as the value that would
146 have been returned by a call to @code{read-char} on the same
147 port. The only difference is that the very next call to
148 @code{read-char} or @code{peek-char} on that @var{port} will
149 return the value returned by the preceding call to
150 @code{peek-char}. In particular, a call to @code{peek-char} on
151 an interactive port will hang waiting for input whenever a call
152 to @code{read-char} would have hung.}
155 @deffn {Scheme Procedure} unread-char cobj [port]
156 @deffnx {C Function} scm_unread_char (cobj, port)
157 Place @var{char} in @var{port} so that it will be read by the
158 next read operation. If called multiple times, the unread characters
159 will be read again in last-in first-out order. If @var{port} is
160 not supplied, the current input port is used.
163 @deffn {Scheme Procedure} unread-string str port
164 @deffnx {C Function} scm_unread_string (str, port)
165 Place the string @var{str} in @var{port} so that its characters will
166 be read from left-to-right as the next characters from @var{port}
167 during subsequent read operations. If called multiple times, the
168 unread characters will be read again in last-in first-out order. If
169 @var{port} is not supplied, the current-input-port is used.
172 @deffn {Scheme Procedure} drain-input port
173 @deffnx {C Function} scm_drain_input (port)
174 This procedure clears a port's input buffers, similar
175 to the way that force-output clears the output buffer. The
176 contents of the buffers are returned as a single string, e.g.,
179 (define p (open-input-file ...))
180 (drain-input p) => empty string, nothing buffered yet.
181 (unread-char (read-char p) p)
182 (drain-input p) => initial chars from p, up to the buffer size.
185 Draining the buffers may be useful for cleanly finishing
186 buffered I/O so that the file descriptor can be used directly
190 @deffn {Scheme Procedure} port-column port
191 @deffnx {Scheme Procedure} port-line port
192 @deffnx {C Function} scm_port_column (port)
193 @deffnx {C Function} scm_port_line (port)
194 Return the current column number or line number of @var{port}.
196 unknown, the result is #f. Otherwise, the result is a 0-origin integer
197 - i.e.@: the first character of the first line is line 0, column 0.
198 (However, when you display a file position, for example in an error
199 message, we recommend you add 1 to get 1-origin integers. This is
200 because lines and column numbers traditionally start with 1, and that is
201 what non-programmers will find most natural.)
204 @deffn {Scheme Procedure} set-port-column! port column
205 @deffnx {Scheme Procedure} set-port-line! port line
206 @deffnx {C Function} scm_set_port_column_x (port, column)
207 @deffnx {C Function} scm_set_port_line_x (port, line)
208 Set the current column or line number of @var{port}.
214 [Generic procedures for writing to ports.]
216 @deffn {Scheme Procedure} get-print-state port
217 @deffnx {C Function} scm_get_print_state (port)
218 Return the print state of the port @var{port}. If @var{port}
219 has no associated print state, @code{#f} is returned.
223 @deffn {Scheme Procedure} write obj [port]
224 Send a representation of @var{obj} to @var{port} or to the current
225 output port if not given.
227 The output is designed to be machine readable, and can be read back
228 with @code{read} (@pxref{Reading}). Strings are printed in
229 doublequotes, with escapes if necessary, and characters are printed in
234 @deffn {Scheme Procedure} display obj [port]
235 Send a representation of @var{obj} to @var{port} or to the current
236 output port if not given.
238 The output is designed for human readability, it differs from
239 @code{write} in that strings are printed without doublequotes and
240 escapes, and characters are printed as per @code{write-char}, not in
245 @deffn {Scheme Procedure} newline [port]
246 @deffnx {C Function} scm_newline (port)
247 Send a newline to @var{port}.
248 If @var{port} is omitted, send to the current output port.
251 @deffn {Scheme Procedure} port-with-print-state port pstate
252 @deffnx {C Function} scm_port_with_print_state (port, pstate)
253 Create a new port which behaves like @var{port}, but with an
254 included print state @var{pstate}.
257 @deffn {Scheme Procedure} print-options-interface [setting]
258 @deffnx {C Function} scm_print_options (setting)
259 Option interface for the print options. Instead of using
260 this procedure directly, use the procedures
261 @code{print-enable}, @code{print-disable}, @code{print-set!}
262 and @code{print-options}.
265 @deffn {Scheme Procedure} simple-format destination message . args
266 @deffnx {C Function} scm_simple_format (destination, message, args)
267 Write @var{message} to @var{destination}, defaulting to
268 the current output port.
269 @var{message} can contain @code{~A} (was @code{%s}) and
270 @code{~S} (was @code{%S}) escapes. When printed,
271 the escapes are replaced with corresponding members of
273 @code{~A} formats using @code{display} and @code{~S} formats
275 If @var{destination} is @code{#t}, then use the current output
276 port, if @var{destination} is @code{#f}, then return a string
277 containing the formatted text. Does not add a trailing newline.
281 @deffn {Scheme Procedure} write-char chr [port]
282 @deffnx {C Function} scm_write_char (chr, port)
283 Send character @var{chr} to @var{port}.
286 @deftypefn {C Function} void scm_c_write (SCM port, const void *buffer, size_t size)
287 Write @var{size} bytes at @var{buffer} to @var{port}.
289 Note that this function does not update @code{port-line} and
290 @code{port-column} (@pxref{Reading}).
294 @deffn {Scheme Procedure} force-output [port]
295 @deffnx {C Function} scm_force_output (port)
296 Flush the specified output port, or the current output port if @var{port}
297 is omitted. The current output buffer contents are passed to the
298 underlying port implementation (e.g., in the case of fports, the
299 data will be written to the file and the output buffer will be cleared.)
300 It has no effect on an unbuffered port.
302 The return value is unspecified.
305 @deffn {Scheme Procedure} flush-all-ports
306 @deffnx {C Function} scm_flush_all_ports ()
307 Equivalent to calling @code{force-output} on
308 all open output ports. The return value is unspecified.
315 @deffn {Scheme Procedure} close-port port
316 @deffnx {C Function} scm_close_port (port)
317 Close the specified port object. Return @code{#t} if it
318 successfully closes a port or @code{#f} if it was already
319 closed. An exception may be raised if an error occurs, for
320 example when flushing buffered output. See also @ref{Ports and
321 File Descriptors, close}, for a procedure which can close file
325 @deffn {Scheme Procedure} close-input-port port
326 @deffnx {Scheme Procedure} close-output-port port
327 @deffnx {C Function} scm_close_input_port (port)
328 @deffnx {C Function} scm_close_output_port (port)
329 @rnindex close-input-port
330 @rnindex close-output-port
331 Close the specified input or output @var{port}. An exception may be
332 raised if an error occurs while closing. If @var{port} is already
333 closed, nothing is done. The return value is unspecified.
335 See also @ref{Ports and File Descriptors, close}, for a procedure
336 which can close file descriptors.
339 @deffn {Scheme Procedure} port-closed? port
340 @deffnx {C Function} scm_port_closed_p (port)
341 Return @code{#t} if @var{port} is closed or @code{#f} if it is
347 @subsection Random Access
349 @deffn {Scheme Procedure} seek fd_port offset whence
350 @deffnx {C Function} scm_seek (fd_port, offset, whence)
351 Sets the current position of @var{fd/port} to the integer
352 @var{offset}, which is interpreted according to the value of
355 One of the following variables should be supplied for
358 Seek from the beginning of the file.
361 Seek from the current position.
364 Seek from the end of the file.
366 If @var{fd/port} is a file descriptor, the underlying system
367 call is @code{lseek}. @var{port} may be a string port.
369 The value returned is the new position in the file. This means
370 that the current position of a port can be obtained using:
372 (seek port 0 SEEK_CUR)
376 @deffn {Scheme Procedure} ftell fd_port
377 @deffnx {C Function} scm_ftell (fd_port)
378 Return an integer representing the current position of
379 @var{fd/port}, measured from the beginning. Equivalent to:
382 (seek port 0 SEEK_CUR)
388 @deffn {Scheme Procedure} truncate-file object [length]
389 @deffnx {C Function} scm_truncate_file (object, length)
390 Truncates the object referred to by @var{object} to at most
391 @var{length} bytes. @var{object} can be a string containing a
392 file name or an integer file descriptor or a port.
393 @var{length} may be omitted if @var{object} is not a file name,
394 in which case the truncation occurs at the current port.
395 position. The return value is unspecified.
399 @subsection Line Oriented and Delimited Text
401 The delimited-I/O module can be accessed with:
404 (use-modules (ice-9 rdelim))
407 It can be used to read or write lines of text, or read text delimited by
408 a specified set of characters. It's similar to the @code{(scsh rdelim)}
409 module from guile-scsh, but does not use multiple values or character
410 sets and has an extra procedure @code{write-line}.
412 @c begin (scm-doc-string "rdelim.scm" "read-line")
413 @deffn {Scheme Procedure} read-line [port] [handle-delim]
414 Return a line of text from @var{port} if specified, otherwise from the
415 value returned by @code{(current-input-port)}. Under Unix, a line of text
416 is terminated by the first end-of-line character or by end-of-file.
418 If @var{handle-delim} is specified, it should be one of the following
422 Discard the terminating delimiter. This is the default, but it will
423 be impossible to tell whether the read terminated with a delimiter or
426 Append the terminating delimiter (if any) to the returned string.
428 Push the terminating delimiter (if any) back on to the port.
430 Return a pair containing the string read from the port and the
431 terminating delimiter or end-of-file object.
435 @c begin (scm-doc-string "rdelim.scm" "read-line!")
436 @deffn {Scheme Procedure} read-line! buf [port]
437 Read a line of text into the supplied string @var{buf} and return the
438 number of characters added to @var{buf}. If @var{buf} is filled, then
439 @code{#f} is returned.
440 Read from @var{port} if
441 specified, otherwise from the value returned by @code{(current-input-port)}.
444 @c begin (scm-doc-string "rdelim.scm" "read-delimited")
445 @deffn {Scheme Procedure} read-delimited delims [port] [handle-delim]
446 Read text until one of the characters in the string @var{delims} is found
447 or end-of-file is reached. Read from @var{port} if supplied, otherwise
448 from the value returned by @code{(current-input-port)}.
449 @var{handle-delim} takes the same values as described for @code{read-line}.
452 @c begin (scm-doc-string "rdelim.scm" "read-delimited!")
453 @deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end]
454 Read text into the supplied string @var{buf} and return the number of
455 characters added to @var{buf} (subject to @var{handle-delim}, which takes
456 the same values specified for @code{read-line}. If @var{buf} is filled,
457 @code{#f} is returned for both the number of characters read and the
458 delimiter. Also terminates if one of the characters in the string
459 @var{delims} is found
460 or end-of-file is reached. Read from @var{port} if supplied, otherwise
461 from the value returned by @code{(current-input-port)}.
464 @deffn {Scheme Procedure} write-line obj [port]
465 @deffnx {C Function} scm_write_line (obj, port)
466 Display @var{obj} and a newline character to @var{port}. If
467 @var{port} is not specified, @code{(current-output-port)} is
468 used. This function is equivalent to:
475 Some of the abovementioned I/O functions rely on the following C
476 primitives. These will mainly be of interest to people hacking Guile
479 @deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]]
480 @deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end)
481 Read characters from @var{port} into @var{str} until one of the
482 characters in the @var{delims} string is encountered. If
483 @var{gobble} is true, discard the delimiter character;
484 otherwise, leave it in the input stream for the next read. If
485 @var{port} is not specified, use the value of
486 @code{(current-input-port)}. If @var{start} or @var{end} are
487 specified, store data only into the substring of @var{str}
488 bounded by @var{start} and @var{end} (which default to the
489 beginning and end of the string, respectively).
491 Return a pair consisting of the delimiter that terminated the
492 string and the number of characters read. If reading stopped
493 at the end of file, the delimiter returned is the
494 @var{eof-object}; if the string was filled without encountering
495 a delimiter, this value is @code{#f}.
498 @deffn {Scheme Procedure} %read-line [port]
499 @deffnx {C Function} scm_read_line (port)
500 Read a newline-terminated line from @var{port}, allocating storage as
501 necessary. The newline terminator (if any) is removed from the string,
502 and a pair consisting of the line and its delimiter is returned. The
503 delimiter may be either a newline or the @var{eof-object}; if
504 @code{%read-line} is called at the end of file, it returns the pair
505 @code{(#<eof> . #<eof>)}.
508 @node Block Reading and Writing
509 @subsection Block reading and writing
511 The Block-string-I/O module can be accessed with:
514 (use-modules (ice-9 rw))
517 It currently contains procedures that help to implement the
518 @code{(scsh rw)} module in guile-scsh.
520 @deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]]
521 @deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end)
522 Read characters from a port or file descriptor into a
523 string @var{str}. A port must have an underlying file
524 descriptor --- a so-called fport. This procedure is
525 scsh-compatible and can efficiently read large strings.
530 attempt to fill the entire string, unless the @var{start}
531 and/or @var{end} arguments are supplied. i.e., @var{start}
532 defaults to 0 and @var{end} defaults to
533 @code{(string-length str)}
535 use the current input port if @var{port_or_fdes} is not
538 return fewer than the requested number of characters in some
539 cases, e.g., on end of file, if interrupted by a signal, or if
540 not all the characters are immediately available.
542 wait indefinitely for some input if no characters are
544 unless the port is in non-blocking mode.
546 read characters from the port's input buffers if available,
547 instead from the underlying file descriptor.
549 return @code{#f} if end-of-file is encountered before reading
550 any characters, otherwise return the number of characters
553 return 0 if the port is in non-blocking mode and no characters
554 are immediately available.
556 return 0 if the request is for 0 bytes, with no
561 @deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]]
562 @deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end)
563 Write characters from a string @var{str} to a port or file
564 descriptor. A port must have an underlying file descriptor
565 --- a so-called fport. This procedure is
566 scsh-compatible and can efficiently write large strings.
571 attempt to write the entire string, unless the @var{start}
572 and/or @var{end} arguments are supplied. i.e., @var{start}
573 defaults to 0 and @var{end} defaults to
574 @code{(string-length str)}
576 use the current output port if @var{port_of_fdes} is not
579 in the case of a buffered port, store the characters in the
580 port's output buffer, if all will fit. If they will not fit
581 then any existing buffered characters will be flushed
583 to write the new characters directly to the underlying file
584 descriptor. If the port is in non-blocking mode and
585 buffered characters can not be flushed immediately, then an
586 @code{EAGAIN} system-error exception will be raised (Note:
587 scsh does not support the use of non-blocking buffered ports.)
589 write fewer than the requested number of
590 characters in some cases, e.g., if interrupted by a signal or
591 if not all of the output can be accepted immediately.
593 wait indefinitely for at least one character
594 from @var{str} to be accepted by the port, unless the port is
595 in non-blocking mode.
597 return the number of characters accepted by the port.
599 return 0 if the port is in non-blocking mode and can not accept
600 at least one character from @var{str} immediately
602 return 0 immediately if the request size is 0 bytes.
607 @subsection Default Ports for Input, Output and Errors
609 @rnindex current-input-port
610 @deffn {Scheme Procedure} current-input-port
611 @deffnx {C Function} scm_current_input_port ()
612 Return the current input port. This is the default port used
613 by many input procedures. Initially, @code{current-input-port}
614 returns the @dfn{standard input} in Unix and C terminology.
617 @rnindex current-output-port
618 @deffn {Scheme Procedure} current-output-port
619 @deffnx {C Function} scm_current_output_port ()
620 Return the current output port. This is the default port used
621 by many output procedures. Initially,
622 @code{current-output-port} returns the @dfn{standard output} in
623 Unix and C terminology.
626 @deffn {Scheme Procedure} current-error-port
627 @deffnx {C Function} scm_current_error_port ()
628 Return the port to which errors and warnings should be sent (the
629 @dfn{standard error} in Unix and C terminology).
632 @deffn {Scheme Procedure} set-current-input-port port
633 @deffnx {Scheme Procedure} set-current-output-port port
634 @deffnx {Scheme Procedure} set-current-error-port port
635 @deffnx {C Function} scm_set_current_input_port (port)
636 @deffnx {C Function} scm_set_current_output_port (port)
637 @deffnx {C Function} scm_set_current_error_port (port)
638 Change the ports returned by @code{current-input-port},
639 @code{current-output-port} and @code{current-error-port}, respectively,
640 so that they use the supplied @var{port} for input or output.
643 @deftypefn {C Function} void scm_frame_current_input_port (SCM port)
644 @deftypefnx {C Function} void scm_frame_current_output_port (SCM port)
645 @deftypefnx {C Function} void scm_frame_current_error_port (SCM port)
646 These functions must be used inside a pair of calls to
647 @code{scm_frame_begin} and @code{scm_frame_end} (@pxref{Frames}).
648 During the dynamic extent of the frame, the indicated port is set to
651 More precisely, the current port is swapped with a `backup' value
652 whenever the frame is entered or left. The backup value is
653 initialized with the @var{port} argument.
657 @subsection Types of Port
659 [Types of port; how to make them.]
662 * File Ports:: Ports on an operating system file.
663 * String Ports:: Ports on a Scheme string.
664 * Soft Ports:: Ports on arbitrary Scheme procedures.
665 * Void Ports:: Ports on nothing at all.
670 @subsubsection File Ports
672 The following procedures are used to open file ports.
673 See also @ref{Ports and File Descriptors, open}, for an interface
674 to the Unix @code{open} system call.
676 Most systems have limits on how many files can be open, so it's
677 strongly recommended that file ports be closed explicitly when no
678 longer required (@pxref{Ports}).
680 @deffn {Scheme Procedure} open-file filename mode
681 @deffnx {C Function} scm_open_file (filename, mode)
682 Open the file whose name is @var{filename}, and return a port
683 representing that file. The attributes of the port are
684 determined by the @var{mode} string. The way in which this is
685 interpreted is similar to C stdio. The first character must be
686 one of the following:
689 Open an existing file for input.
691 Open a file for output, creating it if it doesn't already exist
692 or removing its contents if it does.
694 Open a file for output, creating it if it doesn't already
695 exist. All writes to the port will go to the end of the file.
696 The "append mode" can be turned off while the port is in use
697 @pxref{Ports and File Descriptors, fcntl}
699 The following additional characters can be appended:
702 Open the port for both input and output. E.g., @code{r+}: open
703 an existing file for both input and output.
705 Create an "unbuffered" port. In this case input and output
706 operations are passed directly to the underlying port
707 implementation without additional buffering. This is likely to
708 slow down I/O operations. The buffering mode can be changed
709 while a port is in use @pxref{Ports and File Descriptors,
712 Add line-buffering to the port. The port output buffer will be
713 automatically flushed whenever a newline character is written.
715 In theory we could create read/write ports which were buffered
716 in one direction only. However this isn't included in the
717 current interfaces. If a file cannot be opened with the access
718 requested, @code{open-file} throws an exception.
721 @rnindex open-input-file
722 @deffn {Scheme Procedure} open-input-file filename
723 Open @var{filename} for input. Equivalent to
725 (open-file @var{filename} "r")
729 @rnindex open-output-file
730 @deffn {Scheme Procedure} open-output-file filename
731 Open @var{filename} for output. Equivalent to
733 (open-file @var{filename} "w")
737 @deffn {Scheme Procedure} call-with-input-file filename proc
738 @deffnx {Scheme Procedure} call-with-output-file filename proc
739 @rnindex call-with-input-file
740 @rnindex call-with-output-file
741 Open @var{filename} for input or output, and call @code{(@var{proc}
742 port)} with the resulting port. Return the value returned by
743 @var{proc}. @var{filename} is opened as per @code{open-input-file} or
744 @code{open-output-file} respectively, and an error is signalled if it
747 When @var{proc} returns, the port is closed. If @var{proc} does not
748 return (eg.@: if it throws an error), then the port might not be
749 closed automatically, though it will be garbage collected in the usual
750 way if not otherwise referenced.
753 @deffn {Scheme Procedure} with-input-from-file filename thunk
754 @deffnx {Scheme Procedure} with-output-to-file filename thunk
755 @deffnx {Scheme Procedure} with-error-to-file filename thunk
756 @rnindex with-input-from-file
757 @rnindex with-output-to-file
758 Open @var{filename} and call @code{(@var{thunk})} with the new port
759 setup as respectively the @code{current-input-port},
760 @code{current-output-port}, or @code{current-error-port}. Return the
761 value returned by @var{thunk}. @var{filename} is opened as per
762 @code{open-input-file} or @code{open-output-file} respectively, and an
763 error is signalled if it cannot be opened.
765 When @var{thunk} returns, the port is closed and the previous setting
766 of the respective current port is restored.
768 The current port setting is managed with @code{dynamic-wind}, so the
769 previous value is restored no matter how @var{thunk} exits (eg.@: an
770 exception), and if @var{thunk} is re-entered (via a captured
771 continuation) then it's set again to the @var{FILENAME} port.
773 The port is closed when @var{thunk} returns normally, but not when
774 exited via an exception or new continuation. This ensures it's still
775 ready for use if @var{thunk} is re-entered by a captured continuation.
776 Of course the port is always garbage collected and closed in the usual
777 way when no longer referenced anywhere.
780 @deffn {Scheme Procedure} port-mode port
781 @deffnx {C Function} scm_port_mode (port)
782 Return the port modes associated with the open port @var{port}.
783 These will not necessarily be identical to the modes used when
784 the port was opened, since modes such as "append" which are
785 used only during port creation are not retained.
788 @deffn {Scheme Procedure} port-filename port
789 @deffnx {C Function} scm_port_filename (port)
790 Return the filename associated with @var{port}. This function returns
791 the strings "standard input", "standard output" and "standard error"
792 when called on the current input, output and error ports respectively.
795 @deffn {Scheme Procedure} set-port-filename! port filename
796 @deffnx {C Function} scm_set_port_filename_x (port, filename)
797 Change the filename associated with @var{port}, using the current input
798 port if none is specified. Note that this does not change the port's
799 source of data, but only the value that is returned by
800 @code{port-filename} and reported in diagnostic output.
803 @deffn {Scheme Procedure} file-port? obj
804 @deffnx {C Function} scm_file_port_p (obj)
805 Determine whether @var{obj} is a port that is related to a file.
810 @subsubsection String Ports
812 The following allow string ports to be opened by analogy to R4R*
813 file port facilities:
815 @deffn {Scheme Procedure} call-with-output-string proc
816 @deffnx {C Function} scm_call_with_output_string (proc)
817 Calls the one-argument procedure @var{proc} with a newly created output
818 port. When the function returns, the string composed of the characters
819 written into the port is returned. @var{proc} should not close the port.
822 @deffn {Scheme Procedure} call-with-input-string string proc
823 @deffnx {C Function} scm_call_with_input_string (string, proc)
824 Calls the one-argument procedure @var{proc} with a newly
825 created input port from which @var{string}'s contents may be
826 read. The value yielded by the @var{proc} is returned.
829 @deffn {Scheme Procedure} with-output-to-string thunk
830 Calls the zero-argument procedure @var{thunk} with the current output
831 port set temporarily to a new string port. It returns a string
832 composed of the characters written to the current output.
835 @deffn {Scheme Procedure} with-input-from-string string thunk
836 Calls the zero-argument procedure @var{thunk} with the current input
837 port set temporarily to a string port opened on the specified
838 @var{string}. The value yielded by @var{thunk} is returned.
841 @deffn {Scheme Procedure} open-input-string str
842 @deffnx {C Function} scm_open_input_string (str)
843 Take a string and return an input port that delivers characters
844 from the string. The port can be closed by
845 @code{close-input-port}, though its storage will be reclaimed
846 by the garbage collector if it becomes inaccessible.
849 @deffn {Scheme Procedure} open-output-string
850 @deffnx {C Function} scm_open_output_string ()
851 Return an output port that will accumulate characters for
852 retrieval by @code{get-output-string}. The port can be closed
853 by the procedure @code{close-output-port}, though its storage
854 will be reclaimed by the garbage collector if it becomes
858 @deffn {Scheme Procedure} get-output-string port
859 @deffnx {C Function} scm_get_output_string (port)
860 Given an output port created by @code{open-output-string},
861 return a string consisting of the characters that have been
862 output to the port so far.
864 @code{get-output-string} must be used before closing @var{port}, once
865 closed the string cannot be obtained.
868 A string port can be used in many procedures which accept a port
869 but which are not dependent on implementation details of fports.
870 E.g., seeking and truncating will work on a string port,
871 but trying to extract the file descriptor number will fail.
875 @subsubsection Soft Ports
877 A @dfn{soft-port} is a port based on a vector of procedures capable of
878 accepting or delivering characters. It allows emulation of I/O ports.
880 @deffn {Scheme Procedure} make-soft-port pv modes
881 @deffnx {C Function} scm_make_soft_port (pv, modes)
882 Return a port capable of receiving or delivering characters as
883 specified by the @var{modes} string (@pxref{File Ports,
884 open-file}). @var{pv} must be a vector of length 5 or 6. Its
885 components are as follows:
889 procedure accepting one character for output
891 procedure accepting a string for output
893 thunk for flushing output
895 thunk for getting one character
897 thunk for closing port (not by garbage collection)
899 (if present and not @code{#f}) thunk for computing the number of
900 characters that can be read from the port without blocking.
903 For an output-only port only elements 0, 1, 2, and 4 need be
904 procedures. For an input-only port only elements 3 and 4 need
905 be procedures. Thunks 2 and 4 can instead be @code{#f} if
906 there is no useful operation for them to perform.
908 If thunk 3 returns @code{#f} or an @code{eof-object}
909 (@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
910 Scheme}) it indicates that the port has reached end-of-file.
914 (define stdout (current-output-port))
915 (define p (make-soft-port
917 (lambda (c) (write c stdout))
918 (lambda (s) (display s stdout))
919 (lambda () (display "." stdout))
920 (lambda () (char-upcase (read-char)))
921 (lambda () (display "@@" stdout)))
924 (write p p) @result{} #<input-output: soft 8081e20>
930 @subsubsection Void Ports
932 This kind of port causes any data to be discarded when written to, and
933 always returns the end-of-file object when read from.
935 @deffn {Scheme Procedure} %make-void-port mode
936 @deffnx {C Function} scm_sys_make_void_port (mode)
937 Create and return a new void port. A void port acts like
938 @file{/dev/null}. The @var{mode} argument
939 specifies the input/output modes for this port: see the
940 documentation for @code{open-file} in @ref{File Ports}.
945 @subsection Using and Extending Ports in C
948 * C Port Interface:: Using ports from C.
949 * Port Implementation:: How to implement a new port type in C.
953 @node C Port Interface
954 @subsubsection C Port Interface
956 This section describes how to use Scheme ports from C.
958 @subsubheading Port basics
960 There are two main data structures. A port type object (ptob) is of
961 type @code{scm_ptob_descriptor}. A port instance is of type
962 @code{scm_port}. Given an @code{SCM} variable which points to a port,
963 the corresponding C port object can be obtained using the
964 @code{SCM_PTAB_ENTRY} macro. The ptob can be obtained by using
965 @code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs}
968 @subsubheading Port buffers
970 An input port always has a read buffer and an output port always has a
971 write buffer. However the size of these buffers is not guaranteed to be
972 more than one byte (e.g., the @code{shortbuf} field in @code{scm_port}
973 which is used when no other buffer is allocated). The way in which the
974 buffers are allocated depends on the implementation of the ptob. For
975 example in the case of an fport, buffers may be allocated with malloc
976 when the port is created, but in the case of an strport the underlying
977 string is used as the buffer.
979 @subsubheading The @code{rw_random} flag
981 Special treatment is required for ports which can be seeked at random.
982 Before various operations, such as seeking the port or changing from
983 input to output on a bidirectional port or vice versa, the port
984 implementation must be given a chance to update its state. The write
985 buffer is updated by calling the @code{flush} ptob procedure and the
986 input buffer is updated by calling the @code{end_input} ptob procedure.
987 In the case of an fport, @code{flush} causes buffered output to be
988 written to the file descriptor, while @code{end_input} causes the
989 descriptor position to be adjusted to account for buffered input which
992 The special treatment must be performed if the @code{rw_random} flag in
993 the port is non-zero.
995 @subsubheading The @code{rw_active} variable
997 The @code{rw_active} variable in the port is only used if
998 @code{rw_random} is set. It's defined as an enum with the following
1003 the read buffer may have unread data.
1005 @item SCM_PORT_WRITE
1006 the write buffer may have unwritten data.
1008 @item SCM_PORT_NEITHER
1009 neither the write nor the read buffer has data.
1012 @subsubheading Reading from a port.
1014 To read from a port, it's possible to either call existing libguile
1015 procedures such as @code{scm_getc} and @code{scm_read_line} or to read
1016 data from the read buffer directly. Reading from the buffer involves
1017 the following steps:
1021 Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}.
1024 Fill the read buffer, if it's empty, using @code{scm_fill_input}.
1026 @item Read the data from the buffer and update the read position in
1027 the buffer. Steps 2) and 3) may be repeated as many times as required.
1029 @item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set.
1031 @item update the port's line and column counts.
1034 @subsubheading Writing to a port.
1036 To write data to a port, calling @code{scm_lfwrite} should be sufficient for
1037 most purposes. This takes care of the following steps:
1041 End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}.
1044 Pass the data to the ptob implementation using the @code{write} ptob
1045 procedure. The advantage of using the ptob @code{write} instead of
1046 manipulating the write buffer directly is that it allows the data to be
1047 written in one operation even if the port is using the single-byte
1051 Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random}
1056 @node Port Implementation
1057 @subsubsection Port Implementation
1059 This section describes how to implement a new port type in C.
1061 As described in the previous section, a port type object (ptob) is
1062 a structure of type @code{scm_ptob_descriptor}. A ptob is created by
1063 calling @code{scm_make_port_type}.
1065 All of the elements of the ptob, apart from @code{name}, are procedures
1066 which collectively implement the port behaviour. Creating a new port
1067 type mostly involves writing these procedures.
1069 @code{scm_make_port_type} initializes three elements of the structure
1070 (@code{name}, @code{fill_input} and @code{write}) from its arguments.
1071 The remaining elements are initialized with default values and can be
1072 set later if required.
1076 A pointer to a NUL terminated string: the name of the port type. This
1077 is the only element of @code{scm_ptob_descriptor} which is not
1078 a procedure. Set via the first argument to @code{scm_make_port_type}.
1081 Called during garbage collection to mark any SCM objects that a port
1082 object may contain. It doesn't need to be set unless the port has
1083 @code{SCM} components. Set using @code{scm_set_port_mark}.
1086 Called when the port is collected during gc. It
1087 should free any resources used by the port.
1088 Set using @code{scm_set_port_free}.
1091 Called when @code{write} is called on the port object, to print a
1092 port description. e.g., for an fport it may produce something like:
1093 @code{#<input: /etc/passwd 3>}. Set using @code{scm_set_port_print}.
1096 Not used at present. Set using @code{scm_set_port_equalp}.
1099 Called when the port is closed, unless it was collected during gc. It
1100 should free any resources used by the port.
1101 Set using @code{scm_set_port_close}.
1104 Accept data which is to be written using the port. The port implementation
1105 may choose to buffer the data instead of processing it directly.
1106 Set via the third argument to @code{scm_make_port_type}.
1109 Complete the processing of buffered output data. Reset the value of
1110 @code{rw_active} to @code{SCM_PORT_NEITHER}.
1111 Set using @code{scm_set_port_flush}.
1114 Perform any synchronization required when switching from input to output
1115 on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}.
1116 Set using @code{scm_set_port_end_input}.
1119 Read new data into the read buffer and return the first character. It
1120 can be assumed that the read buffer is empty when this procedure is called.
1121 Set via the second argument to @code{scm_make_port_type}.
1124 Return a lower bound on the number of bytes that could be read from the
1125 port without blocking. It can be assumed that the current state of
1126 @code{rw_active} is @code{SCM_PORT_NEITHER}.
1127 Set using @code{scm_set_port_input_waiting}.
1130 Set the current position of the port. The procedure can not make
1131 any assumptions about the value of @code{rw_active} when it's
1132 called. It can reset the buffers first if desired by using something
1136 if (pt->rw_active == SCM_PORT_READ)
1137 scm_end_input (object);
1138 else if (pt->rw_active == SCM_PORT_WRITE)
1139 ptob->flush (object);
1142 However note that this will have the side effect of discarding any data
1143 in the unread-char buffer, in addition to any side effects from the
1144 @code{end_input} and @code{flush} ptob procedures. This is undesirable
1145 when seek is called to measure the current position of the port, i.e.,
1146 @code{(seek p 0 SEEK_CUR)}. The libguile fport and string port
1147 implementations take care to avoid this problem.
1149 The procedure is set using @code{scm_set_port_seek}.
1152 Truncate the port data to be specified length. It can be assumed that the
1153 current state of @code{rw_active} is @code{SCM_PORT_NEITHER}.
1154 Set using @code{scm_set_port_truncate}.
1160 @c TeX-master: "guile.texi"