Commit | Line | Data |
---|---|---|
a0e07ba4 NJ |
1 | @page |
2 | @node Input and Output | |
3 | @chapter Input and Output | |
4 | ||
5 | @menu | |
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. | |
9401323e | 15 | * I/O Extensions:: Using and extending ports in C. |
a0e07ba4 NJ |
16 | @end menu |
17 | ||
18 | ||
19 | @node Ports | |
20 | @section Ports | |
21 | ||
22 | [Concept of the port abstraction.] | |
23 | ||
24 | Sequential input/output in Scheme is represented by operations on a | |
25 | @dfn{port}. Characters can be read from an input port and | |
26 | written to an output port. This chapter explains the operations | |
27 | that Guile provides for working with ports. | |
28 | ||
29 | The formal definition of a port is very generic: an input port is | |
30 | simply ``an object which can deliver characters on command,'' and | |
31 | an output port is ``an object which can accept characters.'' | |
32 | Because this definition is so loose, it is easy to write functions | |
33 | that simulate ports in software. @dfn{Soft ports} and @dfn{string | |
34 | ports} are two interesting and powerful examples of this technique. | |
35 | ||
36 | @rnindex input-port? | |
8f85c0c6 NJ |
37 | @deffn {Scheme Procedure} input-port? x |
38 | @deffnx {C Function} scm_input_port_p (x) | |
a0e07ba4 NJ |
39 | Return @code{#t} if @var{x} is an input port, otherwise return |
40 | @code{#f}. Any object satisfying this predicate also satisfies | |
41 | @code{port?}. | |
42 | @end deffn | |
43 | ||
44 | @rnindex output-port? | |
8f85c0c6 NJ |
45 | @deffn {Scheme Procedure} output-port? x |
46 | @deffnx {C Function} scm_output_port_p (x) | |
a0e07ba4 NJ |
47 | Return @code{#t} if @var{x} is an output port, otherwise return |
48 | @code{#f}. Any object satisfying this predicate also satisfies | |
49 | @code{port?}. | |
50 | @end deffn | |
51 | ||
8f85c0c6 NJ |
52 | @deffn {Scheme Procedure} port? x |
53 | @deffnx {C Function} scm_port_p (x) | |
a0e07ba4 NJ |
54 | Return a boolean indicating whether @var{x} is a port. |
55 | Equivalent to @code{(or (input-port? @var{x}) (output-port? | |
56 | @var{x}))}. | |
57 | @end deffn | |
58 | ||
59 | ||
60 | @node Reading | |
61 | @section Reading | |
62 | ||
63 | [Generic procedures for reading from ports.] | |
64 | ||
65 | @rnindex eof-object? | |
8f85c0c6 NJ |
66 | @deffn {Scheme Procedure} eof-object? x |
67 | @deffnx {C Function} scm_eof_object_p (x) | |
a0e07ba4 NJ |
68 | Return @code{#t} if @var{x} is an end-of-file object; otherwise |
69 | return @code{#f}. | |
70 | @end deffn | |
71 | ||
72 | @rnindex char-ready? | |
8f85c0c6 NJ |
73 | @deffn {Scheme Procedure} char-ready? [port] |
74 | @deffnx {C Function} scm_char_ready_p (port) | |
a0e07ba4 NJ |
75 | Return @code{#t} if a character is ready on input @var{port} |
76 | and return @code{#f} otherwise. If @code{char-ready?} returns | |
77 | @code{#t} then the next @code{read-char} operation on | |
78 | @var{port} is guaranteed not to hang. If @var{port} is a file | |
79 | port at end of file then @code{char-ready?} returns @code{#t}. | |
80 | @footnote{@code{char-ready?} exists to make it possible for a | |
81 | program to accept characters from interactive ports without | |
82 | getting stuck waiting for input. Any input editors associated | |
83 | with such ports must make sure that characters whose existence | |
84 | has been asserted by @code{char-ready?} cannot be rubbed out. | |
85 | If @code{char-ready?} were to return @code{#f} at end of file, | |
86 | a port at end of file would be indistinguishable from an | |
87 | interactive port that has no ready characters.} | |
88 | @end deffn | |
89 | ||
90 | @rnindex read-char? | |
8f85c0c6 NJ |
91 | @deffn {Scheme Procedure} read-char [port] |
92 | @deffnx {C Function} scm_read_char (port) | |
a0e07ba4 NJ |
93 | Return the next character available from @var{port}, updating |
94 | @var{port} to point to the following character. If no more | |
95 | characters are available, the end-of-file object is returned. | |
96 | @end deffn | |
97 | ||
98 | @rnindex peek-char? | |
8f85c0c6 NJ |
99 | @deffn {Scheme Procedure} peek-char [port] |
100 | @deffnx {C Function} scm_peek_char (port) | |
a0e07ba4 NJ |
101 | Return the next character available from @var{port}, |
102 | @emph{without} updating @var{port} to point to the following | |
103 | character. If no more characters are available, the | |
104 | end-of-file object is returned.@footnote{The value returned by | |
105 | a call to @code{peek-char} is the same as the value that would | |
106 | have been returned by a call to @code{read-char} on the same | |
107 | port. The only difference is that the very next call to | |
108 | @code{read-char} or @code{peek-char} on that @var{port} will | |
109 | return the value returned by the preceding call to | |
110 | @code{peek-char}. In particular, a call to @code{peek-char} on | |
111 | an interactive port will hang waiting for input whenever a call | |
112 | to @code{read-char} would have hung.} | |
113 | @end deffn | |
114 | ||
8f85c0c6 NJ |
115 | @deffn {Scheme Procedure} unread-char cobj [port] |
116 | @deffnx {C Function} scm_unread_char (cobj, port) | |
a0e07ba4 NJ |
117 | Place @var{char} in @var{port} so that it will be read by the |
118 | next read operation. If called multiple times, the unread characters | |
119 | will be read again in last-in first-out order. If @var{port} is | |
120 | not supplied, the current input port is used. | |
121 | @end deffn | |
122 | ||
8f85c0c6 NJ |
123 | @deffn {Scheme Procedure} unread-string str port |
124 | @deffnx {C Function} scm_unread_string (str, port) | |
a0e07ba4 NJ |
125 | Place the string @var{str} in @var{port} so that its characters will be |
126 | read in subsequent read operations. If called multiple times, the | |
127 | unread characters will be read again in last-in first-out order. If | |
128 | @var{port} is not supplied, the current-input-port is used. | |
129 | @end deffn | |
130 | ||
8f85c0c6 NJ |
131 | @deffn {Scheme Procedure} drain-input port |
132 | @deffnx {C Function} scm_drain_input (port) | |
9401323e NJ |
133 | This procedure clears a port's input buffers, similar |
134 | to the way that force-output clears the output buffer. The | |
135 | contents of the buffers are returned as a single string, e.g., | |
136 | ||
137 | @lisp | |
138 | (define p (open-input-file ...)) | |
139 | (drain-input p) => empty string, nothing buffered yet. | |
140 | (unread-char (read-char p) p) | |
141 | (drain-input p) => initial chars from p, up to the buffer size. | |
142 | @end lisp | |
143 | ||
144 | Draining the buffers may be useful for cleanly finishing | |
145 | buffered I/O so that the file descriptor can be used directly | |
146 | for further input. | |
a0e07ba4 NJ |
147 | @end deffn |
148 | ||
8f85c0c6 NJ |
149 | @deffn {Scheme Procedure} port-column port |
150 | @deffnx {Scheme Procedure} port-line port | |
151 | @deffnx {C Function} scm_port_column (port) | |
152 | @deffnx {C Function} scm_port_line (port) | |
a0e07ba4 NJ |
153 | Return the current column number or line number of @var{port}, |
154 | using the current input port if none is specified. If the number is | |
155 | unknown, the result is #f. Otherwise, the result is a 0-origin integer | |
156 | - i.e. the first character of the first line is line 0, column 0. | |
157 | (However, when you display a file position, for example in an error | |
158 | message, we recommend you add 1 to get 1-origin integers. This is | |
159 | because lines and column numbers traditionally start with 1, and that is | |
160 | what non-programmers will find most natural.) | |
161 | @end deffn | |
162 | ||
8f85c0c6 NJ |
163 | @deffn {Scheme Procedure} set-port-column! port column |
164 | @deffnx {Scheme Procedure} set-port-line! port line | |
165 | @deffnx {C Function} scm_set_port_column_x (port, column) | |
166 | @deffnx {C Function} scm_set_port_line_x (port, line) | |
a0e07ba4 NJ |
167 | Set the current column or line number of @var{port}, using the |
168 | current input port if none is specified. | |
169 | @end deffn | |
170 | ||
171 | @node Writing | |
172 | @section Writing | |
173 | ||
174 | [Generic procedures for writing to ports.] | |
175 | ||
8f85c0c6 NJ |
176 | @deffn {Scheme Procedure} get-print-state port |
177 | @deffnx {C Function} scm_get_print_state (port) | |
a0e07ba4 NJ |
178 | Return the print state of the port @var{port}. If @var{port} |
179 | has no associated print state, @code{#f} is returned. | |
180 | @end deffn | |
181 | ||
9eb96786 | 182 | @rnindex display |
8f85c0c6 | 183 | @deffn {Scheme Procedure} display obj [port] |
9eb96786 TTN |
184 | Send a representation of @var{obj} to @var{current-output-port}. |
185 | Optional second arg @var{port} specifies an alternative output port. | |
186 | The representation is similar to that produced by @code{write} (REFFIXME), | |
187 | the differences being strings are not quoted (and their characters are not | |
188 | escaped), and characters are rendered as if with @code{write-char}. | |
189 | @end deffn | |
190 | ||
a0e07ba4 | 191 | @rnindex newline |
8f85c0c6 NJ |
192 | @deffn {Scheme Procedure} newline [port] |
193 | @deffnx {C Function} scm_newline (port) | |
194 | Send a newline to @var{port}. | |
195 | If @var{port} is omitted, send to the current output port. | |
a0e07ba4 NJ |
196 | @end deffn |
197 | ||
8f85c0c6 NJ |
198 | @deffn {Scheme Procedure} port-with-print-state port pstate |
199 | @deffnx {C Function} scm_port_with_print_state (port, pstate) | |
a0e07ba4 NJ |
200 | Create a new port which behaves like @var{port}, but with an |
201 | included print state @var{pstate}. | |
202 | @end deffn | |
203 | ||
8f85c0c6 NJ |
204 | @deffn {Scheme Procedure} print-options-interface [setting] |
205 | @deffnx {C Function} scm_print_options (setting) | |
a0e07ba4 NJ |
206 | Option interface for the print options. Instead of using |
207 | this procedure directly, use the procedures | |
208 | @code{print-enable}, @code{print-disable}, @code{print-set!} | |
209 | and @code{print-options}. | |
210 | @end deffn | |
211 | ||
8f85c0c6 NJ |
212 | @deffn {Scheme Procedure} simple-format destination message . args |
213 | @deffnx {C Function} scm_simple_format (destination, message, args) | |
a0e07ba4 NJ |
214 | Write @var{message} to @var{destination}, defaulting to |
215 | the current output port. | |
216 | @var{message} can contain @code{~A} (was @code{%s}) and | |
217 | @code{~S} (was @code{%S}) escapes. When printed, | |
218 | the escapes are replaced with corresponding members of | |
219 | @var{ARGS}: | |
220 | @code{~A} formats using @code{display} and @code{~S} formats | |
221 | using @code{write}. | |
222 | If @var{destination} is @code{#t}, then use the current output | |
223 | port, if @var{destination} is @code{#f}, then return a string | |
224 | containing the formatted text. Does not add a trailing newline. | |
225 | @end deffn | |
226 | ||
227 | @rnindex write-char | |
8f85c0c6 NJ |
228 | @deffn {Scheme Procedure} write-char chr [port] |
229 | @deffnx {C Function} scm_write_char (chr, port) | |
a0e07ba4 NJ |
230 | Send character @var{chr} to @var{port}. |
231 | @end deffn | |
232 | ||
233 | @findex fflush | |
8f85c0c6 NJ |
234 | @deffn {Scheme Procedure} force-output [port] |
235 | @deffnx {C Function} scm_force_output (port) | |
a0e07ba4 NJ |
236 | Flush the specified output port, or the current output port if @var{port} |
237 | is omitted. The current output buffer contents are passed to the | |
238 | underlying port implementation (e.g., in the case of fports, the | |
239 | data will be written to the file and the output buffer will be cleared.) | |
240 | It has no effect on an unbuffered port. | |
241 | ||
242 | The return value is unspecified. | |
243 | @end deffn | |
244 | ||
8f85c0c6 NJ |
245 | @deffn {Scheme Procedure} flush-all-ports |
246 | @deffnx {C Function} scm_flush_all_ports () | |
a0e07ba4 NJ |
247 | Equivalent to calling @code{force-output} on |
248 | all open output ports. The return value is unspecified. | |
249 | @end deffn | |
250 | ||
251 | ||
252 | @node Closing | |
253 | @section Closing | |
254 | ||
8f85c0c6 NJ |
255 | @deffn {Scheme Procedure} close-port port |
256 | @deffnx {C Function} scm_close_port (port) | |
a0e07ba4 NJ |
257 | Close the specified port object. Return @code{#t} if it |
258 | successfully closes a port or @code{#f} if it was already | |
259 | closed. An exception may be raised if an error occurs, for | |
260 | example when flushing buffered output. See also @ref{Ports and | |
261 | File Descriptors, close}, for a procedure which can close file | |
262 | descriptors. | |
263 | @end deffn | |
264 | ||
265 | @rnindex close-input-port | |
8f85c0c6 NJ |
266 | @deffn {Scheme Procedure} close-input-port port |
267 | @deffnx {C Function} scm_close_input_port (port) | |
a0e07ba4 NJ |
268 | Close the specified input port object. The routine has no effect if |
269 | the file has already been closed. An exception may be raised if an | |
270 | error occurs. The value returned is unspecified. | |
271 | ||
272 | See also @ref{Ports and File Descriptors, close}, for a procedure | |
273 | which can close file descriptors. | |
274 | @end deffn | |
275 | ||
276 | @rnindex close-output-port | |
8f85c0c6 NJ |
277 | @deffn {Scheme Procedure} close-output-port port |
278 | @deffnx {C Function} scm_close_output_port (port) | |
a0e07ba4 NJ |
279 | Close the specified output port object. The routine has no effect if |
280 | the file has already been closed. An exception may be raised if an | |
281 | error occurs. The value returned is unspecified. | |
282 | ||
283 | See also @ref{Ports and File Descriptors, close}, for a procedure | |
284 | which can close file descriptors. | |
285 | @end deffn | |
286 | ||
8f85c0c6 NJ |
287 | @deffn {Scheme Procedure} port-closed? port |
288 | @deffnx {C Function} scm_port_closed_p (port) | |
a0e07ba4 NJ |
289 | Return @code{#t} if @var{port} is closed or @code{#f} if it is |
290 | open. | |
291 | @end deffn | |
292 | ||
293 | ||
294 | @node Random Access | |
295 | @section Random Access | |
296 | ||
8f85c0c6 NJ |
297 | @deffn {Scheme Procedure} seek fd_port offset whence |
298 | @deffnx {C Function} scm_seek (fd_port, offset, whence) | |
a0e07ba4 NJ |
299 | Sets the current position of @var{fd/port} to the integer |
300 | @var{offset}, which is interpreted according to the value of | |
301 | @var{whence}. | |
302 | ||
303 | One of the following variables should be supplied for | |
304 | @var{whence}: | |
305 | @defvar SEEK_SET | |
306 | Seek from the beginning of the file. | |
307 | @end defvar | |
308 | @defvar SEEK_CUR | |
309 | Seek from the current position. | |
310 | @end defvar | |
311 | @defvar SEEK_END | |
312 | Seek from the end of the file. | |
313 | @end defvar | |
314 | If @var{fd/port} is a file descriptor, the underlying system | |
315 | call is @code{lseek}. @var{port} may be a string port. | |
316 | ||
317 | The value returned is the new position in the file. This means | |
318 | that the current position of a port can be obtained using: | |
319 | @lisp | |
320 | (seek port 0 SEEK_CUR) | |
321 | @end lisp | |
322 | @end deffn | |
323 | ||
8f85c0c6 NJ |
324 | @deffn {Scheme Procedure} ftell fd_port |
325 | @deffnx {C Function} scm_ftell (fd_port) | |
a0e07ba4 NJ |
326 | Return an integer representing the current position of |
327 | @var{fd/port}, measured from the beginning. Equivalent to: | |
328 | ||
329 | @lisp | |
330 | (seek port 0 SEEK_CUR) | |
331 | @end lisp | |
332 | @end deffn | |
333 | ||
334 | @findex truncate | |
335 | @findex ftruncate | |
8f85c0c6 NJ |
336 | @deffn {Scheme Procedure} truncate-file object [length] |
337 | @deffnx {C Function} scm_truncate_file (object, length) | |
a0e07ba4 NJ |
338 | Truncates the object referred to by @var{object} to at most |
339 | @var{length} bytes. @var{object} can be a string containing a | |
340 | file name or an integer file descriptor or a port. | |
341 | @var{length} may be omitted if @var{object} is not a file name, | |
342 | in which case the truncation occurs at the current port. | |
343 | position. The return value is unspecified. | |
344 | @end deffn | |
345 | ||
346 | @node Line/Delimited | |
347 | @section Line Oriented and Delimited Text | |
348 | ||
349 | The delimited-I/O module can be accessed with: | |
350 | ||
351 | @smalllisp | |
352 | (use-modules (ice-9 rdelim)) | |
353 | @end smalllisp | |
354 | ||
355 | It can be used to read or write lines of text, or read text delimited by | |
356 | a specified set of characters. It's similar to the @code{(scsh rdelim)} | |
357 | module from guile-scsh, but does not use multiple values or character | |
358 | sets and has an extra procedure @code{write-line}. | |
359 | ||
360 | @c begin (scm-doc-string "rdelim.scm" "read-line") | |
8f85c0c6 | 361 | @deffn {Scheme Procedure} read-line [port] [handle-delim] |
a0e07ba4 NJ |
362 | Return a line of text from @var{port} if specified, otherwise from the |
363 | value returned by @code{(current-input-port)}. Under Unix, a line of text | |
364 | is terminated by the first end-of-line character or by end-of-file. | |
365 | ||
366 | If @var{handle-delim} is specified, it should be one of the following | |
367 | symbols: | |
368 | @table @code | |
369 | @item trim | |
370 | Discard the terminating delimiter. This is the default, but it will | |
371 | be impossible to tell whether the read terminated with a delimiter or | |
372 | end-of-file. | |
373 | @item concat | |
374 | Append the terminating delimiter (if any) to the returned string. | |
375 | @item peek | |
376 | Push the terminating delimiter (if any) back on to the port. | |
377 | @item split | |
378 | Return a pair containing the string read from the port and the | |
379 | terminating delimiter or end-of-file object. | |
380 | @end table | |
381 | @end deffn | |
382 | ||
383 | @c begin (scm-doc-string "rdelim.scm" "read-line!") | |
8f85c0c6 | 384 | @deffn {Scheme Procedure} read-line! buf [port] |
a0e07ba4 NJ |
385 | Read a line of text into the supplied string @var{buf} and return the |
386 | number of characters added to @var{buf}. If @var{buf} is filled, then | |
387 | @code{#f} is returned. | |
388 | Read from @var{port} if | |
389 | specified, otherwise from the value returned by @code{(current-input-port)}. | |
390 | @end deffn | |
391 | ||
392 | @c begin (scm-doc-string "rdelim.scm" "read-delimited") | |
8f85c0c6 | 393 | @deffn {Scheme Procedure} read-delimited delims [port] [handle-delim] |
a0e07ba4 NJ |
394 | Read text until one of the characters in the string @var{delims} is found |
395 | or end-of-file is reached. Read from @var{port} if supplied, otherwise | |
396 | from the value returned by @code{(current-input-port)}. | |
397 | @var{handle-delim} takes the same values as described for @code{read-line}. | |
398 | @end deffn | |
399 | ||
400 | @c begin (scm-doc-string "rdelim.scm" "read-delimited!") | |
8f85c0c6 | 401 | @deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end] |
a0e07ba4 NJ |
402 | Read text into the supplied string @var{buf} and return the number of |
403 | characters added to @var{buf} (subject to @var{handle-delim}, which takes | |
404 | the same values specified for @code{read-line}. If @var{buf} is filled, | |
405 | @code{#f} is returned for both the number of characters read and the | |
406 | delimiter. Also terminates if one of the characters in the string | |
407 | @var{delims} is found | |
408 | or end-of-file is reached. Read from @var{port} if supplied, otherwise | |
409 | from the value returned by @code{(current-input-port)}. | |
410 | @end deffn | |
411 | ||
8f85c0c6 NJ |
412 | @deffn {Scheme Procedure} write-line obj [port] |
413 | @deffnx {C Function} scm_write_line (obj, port) | |
a0e07ba4 NJ |
414 | Display @var{obj} and a newline character to @var{port}. If |
415 | @var{port} is not specified, @code{(current-output-port)} is | |
416 | used. This function is equivalent to: | |
417 | @lisp | |
418 | (display obj [port]) | |
419 | (newline [port]) | |
420 | @end lisp | |
421 | @end deffn | |
422 | ||
423 | Some of the abovementioned I/O functions rely on the following C | |
424 | primitives. These will mainly be of interest to people hacking Guile | |
425 | internals. | |
426 | ||
8f85c0c6 NJ |
427 | @deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]] |
428 | @deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end) | |
a0e07ba4 NJ |
429 | Read characters from @var{port} into @var{str} until one of the |
430 | characters in the @var{delims} string is encountered. If | |
431 | @var{gobble} is true, discard the delimiter character; | |
432 | otherwise, leave it in the input stream for the next read. If | |
433 | @var{port} is not specified, use the value of | |
434 | @code{(current-input-port)}. If @var{start} or @var{end} are | |
435 | specified, store data only into the substring of @var{str} | |
436 | bounded by @var{start} and @var{end} (which default to the | |
437 | beginning and end of the string, respectively). | |
438 | ||
439 | Return a pair consisting of the delimiter that terminated the | |
440 | string and the number of characters read. If reading stopped | |
441 | at the end of file, the delimiter returned is the | |
442 | @var{eof-object}; if the string was filled without encountering | |
443 | a delimiter, this value is @code{#f}. | |
444 | @end deffn | |
445 | ||
8f85c0c6 NJ |
446 | @deffn {Scheme Procedure} %read-line [port] |
447 | @deffnx {C Function} scm_read_line (port) | |
a0e07ba4 NJ |
448 | Read a newline-terminated line from @var{port}, allocating storage as |
449 | necessary. The newline terminator (if any) is removed from the string, | |
450 | and a pair consisting of the line and its delimiter is returned. The | |
451 | delimiter may be either a newline or the @var{eof-object}; if | |
452 | @code{%read-line} is called at the end of file, it returns the pair | |
453 | @code{(#<eof> . #<eof>)}. | |
454 | @end deffn | |
455 | ||
456 | @node Block Reading and Writing | |
457 | @section Block reading and writing | |
458 | ||
459 | The Block-string-I/O module can be accessed with: | |
460 | ||
461 | @smalllisp | |
462 | (use-modules (ice-9 rw)) | |
463 | @end smalllisp | |
464 | ||
465 | It currently contains procedures that help to implement the | |
466 | @code{(scsh rw)} module in guile-scsh. | |
467 | ||
8f85c0c6 NJ |
468 | @deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]] |
469 | @deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end) | |
a0e07ba4 NJ |
470 | Read characters from a port or file descriptor into a |
471 | string @var{str}. A port must have an underlying file | |
472 | descriptor --- a so-called fport. This procedure is | |
473 | scsh-compatible and can efficiently read large strings. | |
474 | It will: | |
475 | ||
476 | @itemize | |
477 | @item | |
478 | attempt to fill the entire string, unless the @var{start} | |
479 | and/or @var{end} arguments are supplied. i.e., @var{start} | |
480 | defaults to 0 and @var{end} defaults to | |
481 | @code{(string-length str)} | |
482 | @item | |
483 | use the current input port if @var{port_or_fdes} is not | |
484 | supplied. | |
485 | @item | |
486 | return fewer than the requested number of characters in some | |
487 | cases, e.g., on end of file, if interrupted by a signal, or if | |
488 | not all the characters are immediately available. | |
489 | @item | |
490 | wait indefinitely for some input if no characters are | |
491 | currently available, | |
492 | unless the port is in non-blocking mode. | |
493 | @item | |
494 | read characters from the port's input buffers if available, | |
495 | instead from the underlying file descriptor. | |
496 | @item | |
497 | return @code{#f} if end-of-file is encountered before reading | |
498 | any characters, otherwise return the number of characters | |
499 | read. | |
500 | @item | |
501 | return 0 if the port is in non-blocking mode and no characters | |
502 | are immediately available. | |
503 | @item | |
504 | return 0 if the request is for 0 bytes, with no | |
505 | end-of-file check. | |
506 | @end itemize | |
507 | @end deffn | |
508 | ||
8f85c0c6 NJ |
509 | @deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]] |
510 | @deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end) | |
a0e07ba4 NJ |
511 | Write characters from a string @var{str} to a port or file |
512 | descriptor. A port must have an underlying file descriptor | |
513 | --- a so-called fport. This procedure is | |
514 | scsh-compatible and can efficiently write large strings. | |
515 | It will: | |
516 | ||
517 | @itemize | |
518 | @item | |
519 | attempt to write the entire string, unless the @var{start} | |
520 | and/or @var{end} arguments are supplied. i.e., @var{start} | |
521 | defaults to 0 and @var{end} defaults to | |
522 | @code{(string-length str)} | |
523 | @item | |
524 | use the current output port if @var{port_of_fdes} is not | |
525 | supplied. | |
526 | @item | |
527 | in the case of a buffered port, store the characters in the | |
528 | port's output buffer, if all will fit. If they will not fit | |
529 | then any existing buffered characters will be flushed | |
530 | before attempting | |
531 | to write the new characters directly to the underlying file | |
532 | descriptor. If the port is in non-blocking mode and | |
533 | buffered characters can not be flushed immediately, then an | |
534 | @code{EAGAIN} system-error exception will be raised (Note: | |
535 | scsh does not support the use of non-blocking buffered ports.) | |
536 | @item | |
537 | write fewer than the requested number of | |
538 | characters in some cases, e.g., if interrupted by a signal or | |
539 | if not all of the output can be accepted immediately. | |
540 | @item | |
541 | wait indefinitely for at least one character | |
542 | from @var{str} to be accepted by the port, unless the port is | |
543 | in non-blocking mode. | |
544 | @item | |
545 | return the number of characters accepted by the port. | |
546 | @item | |
547 | return 0 if the port is in non-blocking mode and can not accept | |
548 | at least one character from @var{str} immediately | |
549 | @item | |
550 | return 0 immediately if the request size is 0 bytes. | |
551 | @end itemize | |
552 | @end deffn | |
553 | ||
554 | @node Default Ports | |
555 | @section Default Ports for Input, Output and Errors | |
556 | ||
557 | @rnindex current-input-port | |
8f85c0c6 NJ |
558 | @deffn {Scheme Procedure} current-input-port |
559 | @deffnx {C Function} scm_current_input_port () | |
a0e07ba4 NJ |
560 | Return the current input port. This is the default port used |
561 | by many input procedures. Initially, @code{current-input-port} | |
562 | returns the @dfn{standard input} in Unix and C terminology. | |
563 | @end deffn | |
564 | ||
565 | @rnindex current-output-port | |
8f85c0c6 NJ |
566 | @deffn {Scheme Procedure} current-output-port |
567 | @deffnx {C Function} scm_current_output_port () | |
a0e07ba4 NJ |
568 | Return the current output port. This is the default port used |
569 | by many output procedures. Initially, | |
570 | @code{current-output-port} returns the @dfn{standard output} in | |
571 | Unix and C terminology. | |
572 | @end deffn | |
573 | ||
8f85c0c6 NJ |
574 | @deffn {Scheme Procedure} current-error-port |
575 | @deffnx {C Function} scm_current_error_port () | |
a0e07ba4 NJ |
576 | Return the port to which errors and warnings should be sent (the |
577 | @dfn{standard error} in Unix and C terminology). | |
578 | @end deffn | |
579 | ||
8f85c0c6 NJ |
580 | @deffn {Scheme Procedure} set-current-input-port port |
581 | @deffnx {Scheme Procedure} set-current-output-port port | |
582 | @deffnx {Scheme Procedure} set-current-error-port port | |
583 | @deffnx {C Function} scm_set_current_input_port (port) | |
584 | @deffnx {C Function} scm_set_current_output_port (port) | |
585 | @deffnx {C Function} scm_set_current_error_port (port) | |
a0e07ba4 NJ |
586 | Change the ports returned by @code{current-input-port}, |
587 | @code{current-output-port} and @code{current-error-port}, respectively, | |
588 | so that they use the supplied @var{port} for input or output. | |
589 | @end deffn | |
590 | ||
8f85c0c6 | 591 | @deffn {Scheme Procedure} set-current-output-port port |
a0e07ba4 NJ |
592 | Set the current default output port to PORT. |
593 | @end deffn | |
594 | ||
8f85c0c6 | 595 | @deffn {Scheme Procedure} set-current-error-port port |
a0e07ba4 NJ |
596 | Set the current default error port to PORT. |
597 | @end deffn | |
598 | ||
599 | ||
600 | @node Port Types | |
601 | @section Types of Port | |
602 | ||
603 | [Types of port; how to make them.] | |
604 | ||
605 | @menu | |
606 | * File Ports:: Ports on an operating system file. | |
607 | * String Ports:: Ports on a Scheme string. | |
608 | * Soft Ports:: Ports on arbitrary Scheme procedures. | |
609 | * Void Ports:: Ports on nothing at all. | |
610 | @end menu | |
611 | ||
612 | ||
613 | @node File Ports | |
614 | @subsection File Ports | |
615 | ||
616 | The following procedures are used to open file ports. | |
617 | See also @ref{Ports and File Descriptors, open}, for an interface | |
618 | to the Unix @code{open} system call. | |
619 | ||
8f85c0c6 NJ |
620 | @deffn {Scheme Procedure} open-file filename mode |
621 | @deffnx {C Function} scm_open_file (filename, mode) | |
a0e07ba4 NJ |
622 | Open the file whose name is @var{filename}, and return a port |
623 | representing that file. The attributes of the port are | |
624 | determined by the @var{mode} string. The way in which this is | |
625 | interpreted is similar to C stdio. The first character must be | |
626 | one of the following: | |
627 | @table @samp | |
628 | @item r | |
629 | Open an existing file for input. | |
630 | @item w | |
631 | Open a file for output, creating it if it doesn't already exist | |
632 | or removing its contents if it does. | |
633 | @item a | |
634 | Open a file for output, creating it if it doesn't already | |
635 | exist. All writes to the port will go to the end of the file. | |
636 | The "append mode" can be turned off while the port is in use | |
637 | @pxref{Ports and File Descriptors, fcntl} | |
638 | @end table | |
639 | The following additional characters can be appended: | |
640 | @table @samp | |
641 | @item + | |
642 | Open the port for both input and output. E.g., @code{r+}: open | |
643 | an existing file for both input and output. | |
644 | @item 0 | |
645 | Create an "unbuffered" port. In this case input and output | |
646 | operations are passed directly to the underlying port | |
647 | implementation without additional buffering. This is likely to | |
648 | slow down I/O operations. The buffering mode can be changed | |
649 | while a port is in use @pxref{Ports and File Descriptors, | |
650 | setvbuf} | |
651 | @item l | |
652 | Add line-buffering to the port. The port output buffer will be | |
653 | automatically flushed whenever a newline character is written. | |
654 | @end table | |
655 | In theory we could create read/write ports which were buffered | |
656 | in one direction only. However this isn't included in the | |
657 | current interfaces. If a file cannot be opened with the access | |
658 | requested, @code{open-file} throws an exception. | |
659 | @end deffn | |
660 | ||
661 | @rnindex open-input-file | |
8f85c0c6 | 662 | @deffn {Scheme Procedure} open-input-file filename |
a0e07ba4 NJ |
663 | Open @var{filename} for input. Equivalent to |
664 | @smalllisp | |
665 | (open-file @var{filename} "r") | |
666 | @end smalllisp | |
667 | @end deffn | |
668 | ||
669 | @rnindex open-output-file | |
8f85c0c6 | 670 | @deffn {Scheme Procedure} open-output-file filename |
a0e07ba4 NJ |
671 | Open @var{filename} for output. Equivalent to |
672 | @smalllisp | |
673 | (open-file @var{filename} "w") | |
674 | @end smalllisp | |
675 | @end deffn | |
676 | ||
677 | @rnindex call-with-input-file | |
8f85c0c6 | 678 | @deffn {Scheme Procedure} call-with-input-file file proc |
a0e07ba4 NJ |
679 | @var{proc} should be a procedure of one argument, and @var{file} should |
680 | be a string naming a file. The file must already exist. These | |
681 | procedures call @var{proc} with one argument: the port obtained by | |
682 | opening the named file for input or output. If the file cannot be | |
683 | opened, an error is signalled. If the procedure returns, then the port | |
684 | is closed automatically and the value yielded by the procedure is | |
685 | returned. If the procedure does not return, then the port will not be | |
686 | closed automatically unless it is possible to prove that the port will | |
687 | never again be used for a read or write operation. | |
688 | @end deffn | |
689 | ||
690 | @rnindex call-with-output-file | |
8f85c0c6 | 691 | @deffn {Scheme Procedure} call-with-output-file file proc |
a0e07ba4 NJ |
692 | @var{proc} should be a procedure of one argument, and @var{file} should |
693 | be a string naming a file. The behaviour is unspecified if the file | |
694 | already exists. These procedures call @var{proc} with one argument: the | |
695 | port obtained by opening the named file for input or output. If the | |
696 | file cannot be opened, an error is signalled. If the procedure returns, | |
697 | then the port is closed automatically and the value yielded by the | |
698 | procedure is returned. If the procedure does not return, then the port | |
699 | will not be closed automatically unless it is possible to prove that the | |
700 | port will never again be used for a read or write operation. | |
701 | @end deffn | |
702 | ||
703 | @rnindex with-input-from-file | |
8f85c0c6 | 704 | @deffn {Scheme Procedure} with-input-from-file file thunk |
a0e07ba4 NJ |
705 | @var{thunk} must be a procedure of no arguments, and @var{file} must be |
706 | a string naming a file. The file must already exist. The file is opened | |
707 | for input, an input port connected to it is made the default value | |
708 | returned by @code{current-input-port}, and the @var{thunk} is called | |
709 | with no arguments. When the @var{thunk} returns, the port is closed and | |
710 | the previous default is restored. Returns the value yielded by | |
711 | @var{thunk}. If an escape procedure is used to escape from the | |
712 | continuation of these procedures, their behavior is implementation | |
713 | dependent. | |
714 | @end deffn | |
715 | ||
716 | @rnindex with-output-to-file | |
8f85c0c6 | 717 | @deffn {Scheme Procedure} with-output-to-file file thunk |
a0e07ba4 NJ |
718 | @var{thunk} must be a procedure of no arguments, and @var{file} must be |
719 | a string naming a file. The effect is unspecified if the file already | |
720 | exists. The file is opened for output, an output port connected to it | |
721 | is made the default value returned by @code{current-output-port}, and | |
722 | the @var{thunk} is called with no arguments. When the @var{thunk} | |
723 | returns, the port is closed and the previous default is restored. | |
724 | Returns the value yielded by @var{thunk}. If an escape procedure is | |
725 | used to escape from the continuation of these procedures, their behavior | |
726 | is implementation dependent. | |
727 | @end deffn | |
728 | ||
8f85c0c6 | 729 | @deffn {Scheme Procedure} with-error-to-file file thunk |
a0e07ba4 NJ |
730 | @var{thunk} must be a procedure of no arguments, and @var{file} must be |
731 | a string naming a file. The effect is unspecified if the file already | |
732 | exists. The file is opened for output, an output port connected to it | |
733 | is made the default value returned by @code{current-error-port}, and the | |
734 | @var{thunk} is called with no arguments. When the @var{thunk} returns, | |
735 | the port is closed and the previous default is restored. Returns the | |
736 | value yielded by @var{thunk}. If an escape procedure is used to escape | |
737 | from the continuation of these procedures, their behavior is | |
738 | implementation dependent. | |
739 | @end deffn | |
740 | ||
8f85c0c6 NJ |
741 | @deffn {Scheme Procedure} port-mode port |
742 | @deffnx {C Function} scm_port_mode (port) | |
743 | Return the port modes associated with the open port @var{port}. | |
744 | These will not necessarily be identical to the modes used when | |
745 | the port was opened, since modes such as "append" which are | |
746 | used only during port creation are not retained. | |
a0e07ba4 NJ |
747 | @end deffn |
748 | ||
8f85c0c6 NJ |
749 | @deffn {Scheme Procedure} port-filename port |
750 | @deffnx {C Function} scm_port_filename (port) | |
a0e07ba4 NJ |
751 | Return the filename associated with @var{port}. This function returns |
752 | the strings "standard input", "standard output" and "standard error" | |
753 | when called on the current input, output and error ports respectively. | |
754 | @end deffn | |
755 | ||
8f85c0c6 NJ |
756 | @deffn {Scheme Procedure} set-port-filename! port filename |
757 | @deffnx {C Function} scm_set_port_filename_x (port, filename) | |
a0e07ba4 NJ |
758 | Change the filename associated with @var{port}, using the current input |
759 | port if none is specified. Note that this does not change the port's | |
760 | source of data, but only the value that is returned by | |
761 | @code{port-filename} and reported in diagnostic output. | |
762 | @end deffn | |
763 | ||
8f85c0c6 NJ |
764 | @deffn {Scheme Procedure} file-port? obj |
765 | @deffnx {C Function} scm_file_port_p (obj) | |
a0e07ba4 NJ |
766 | Determine whether @var{obj} is a port that is related to a file. |
767 | @end deffn | |
768 | ||
769 | ||
770 | @node String Ports | |
771 | @subsection String Ports | |
772 | ||
773 | The following allow string ports to be opened by analogy to R4R* | |
774 | file port facilities: | |
775 | ||
8f85c0c6 NJ |
776 | @deffn {Scheme Procedure} call-with-output-string proc |
777 | @deffnx {C Function} scm_call_with_output_string (proc) | |
a0e07ba4 NJ |
778 | Calls the one-argument procedure @var{proc} with a newly created output |
779 | port. When the function returns, the string composed of the characters | |
780 | written into the port is returned. | |
781 | @end deffn | |
782 | ||
8f85c0c6 NJ |
783 | @deffn {Scheme Procedure} call-with-input-string string proc |
784 | @deffnx {C Function} scm_call_with_input_string (string, proc) | |
a0e07ba4 NJ |
785 | Calls the one-argument procedure @var{proc} with a newly |
786 | created input port from which @var{string}'s contents may be | |
787 | read. The value yielded by the @var{proc} is returned. | |
788 | @end deffn | |
789 | ||
8f85c0c6 | 790 | @deffn {Scheme Procedure} with-output-to-string thunk |
a0e07ba4 NJ |
791 | Calls the zero-argument procedure @var{thunk} with the current output |
792 | port set temporarily to a new string port. It returns a string | |
793 | composed of the characters written to the current output. | |
794 | @end deffn | |
795 | ||
8f85c0c6 | 796 | @deffn {Scheme Procedure} with-input-from-string string thunk |
a0e07ba4 NJ |
797 | Calls the zero-argument procedure @var{thunk} with the current input |
798 | port set temporarily to a string port opened on the specified | |
799 | @var{string}. The value yielded by @var{thunk} is returned. | |
800 | @end deffn | |
801 | ||
8f85c0c6 NJ |
802 | @deffn {Scheme Procedure} open-input-string str |
803 | @deffnx {C Function} scm_open_input_string (str) | |
a0e07ba4 NJ |
804 | Take a string and return an input port that delivers characters |
805 | from the string. The port can be closed by | |
806 | @code{close-input-port}, though its storage will be reclaimed | |
807 | by the garbage collector if it becomes inaccessible. | |
808 | @end deffn | |
809 | ||
8f85c0c6 NJ |
810 | @deffn {Scheme Procedure} open-output-string |
811 | @deffnx {C Function} scm_open_output_string () | |
a0e07ba4 NJ |
812 | Return an output port that will accumulate characters for |
813 | retrieval by @code{get-output-string}. The port can be closed | |
814 | by the procedure @code{close-output-port}, though its storage | |
815 | will be reclaimed by the garbage collector if it becomes | |
816 | inaccessible. | |
817 | @end deffn | |
818 | ||
8f85c0c6 NJ |
819 | @deffn {Scheme Procedure} get-output-string port |
820 | @deffnx {C Function} scm_get_output_string (port) | |
a0e07ba4 NJ |
821 | Given an output port created by @code{open-output-string}, |
822 | return a string consisting of the characters that have been | |
823 | output to the port so far. | |
824 | @end deffn | |
825 | ||
826 | A string port can be used in many procedures which accept a port | |
827 | but which are not dependent on implementation details of fports. | |
828 | E.g., seeking and truncating will work on a string port, | |
829 | but trying to extract the file descriptor number will fail. | |
830 | ||
831 | ||
832 | @node Soft Ports | |
833 | @subsection Soft Ports | |
834 | ||
835 | A @dfn{soft-port} is a port based on a vector of procedures capable of | |
836 | accepting or delivering characters. It allows emulation of I/O ports. | |
837 | ||
8f85c0c6 NJ |
838 | @deffn {Scheme Procedure} make-soft-port pv modes |
839 | @deffnx {C Function} scm_make_soft_port (pv, modes) | |
a0e07ba4 NJ |
840 | Return a port capable of receiving or delivering characters as |
841 | specified by the @var{modes} string (@pxref{File Ports, | |
842 | open-file}). @var{pv} must be a vector of length 5. Its | |
843 | components are as follows: | |
844 | ||
845 | @enumerate 0 | |
846 | @item | |
847 | procedure accepting one character for output | |
848 | @item | |
849 | procedure accepting a string for output | |
850 | @item | |
851 | thunk for flushing output | |
852 | @item | |
853 | thunk for getting one character | |
854 | @item | |
855 | thunk for closing port (not by garbage collection) | |
856 | @end enumerate | |
857 | ||
858 | For an output-only port only elements 0, 1, 2, and 4 need be | |
859 | procedures. For an input-only port only elements 3 and 4 need | |
860 | be procedures. Thunks 2 and 4 can instead be @code{#f} if | |
861 | there is no useful operation for them to perform. | |
862 | ||
863 | If thunk 3 returns @code{#f} or an @code{eof-object} | |
864 | (@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on | |
865 | Scheme}) it indicates that the port has reached end-of-file. | |
866 | For example: | |
867 | ||
868 | @lisp | |
869 | (define stdout (current-output-port)) | |
870 | (define p (make-soft-port | |
871 | (vector | |
872 | (lambda (c) (write c stdout)) | |
873 | (lambda (s) (display s stdout)) | |
874 | (lambda () (display "." stdout)) | |
875 | (lambda () (char-upcase (read-char))) | |
876 | (lambda () (display "@@" stdout))) | |
877 | "rw")) | |
878 | ||
879 | (write p p) @result{} #<input-output: soft 8081e20> | |
880 | @end lisp | |
881 | @end deffn | |
882 | ||
883 | ||
884 | @node Void Ports | |
885 | @subsection Void Ports | |
886 | ||
887 | This kind of port causes any data to be discarded when written to, and | |
888 | always returns the end-of-file object when read from. | |
889 | ||
8f85c0c6 NJ |
890 | @deffn {Scheme Procedure} %make-void-port mode |
891 | @deffnx {C Function} scm_sys_make_void_port (mode) | |
a0e07ba4 | 892 | Create and return a new void port. A void port acts like |
8f85c0c6 NJ |
893 | /dev/null. The @var{mode} argument |
894 | specifies the input/output modes for this port: see the | |
895 | documentation for @code{open-file} in @ref{File Ports}. | |
a0e07ba4 NJ |
896 | @end deffn |
897 | ||
898 | ||
9401323e NJ |
899 | @node I/O Extensions |
900 | @section Using and Extending Ports in C | |
901 | ||
902 | @menu | |
903 | * C Port Interface:: Using ports from C. | |
904 | * Port Implementation:: How to implement a new port type in C. | |
905 | @end menu | |
906 | ||
907 | ||
908 | @node C Port Interface | |
909 | @subsection C Port Interface | |
910 | ||
911 | This section describes how to use Scheme ports from C. | |
912 | ||
913 | @subsubsection Port basics | |
914 | ||
915 | There are two main data structures. A port type object (ptob) is of | |
916 | type @code{scm_ptob_descriptor}. A port instance is of type | |
917 | @code{scm_port}. Given an @code{SCM} variable which points to a port, | |
918 | the corresponding C port object can be obtained using the | |
919 | @code{SCM_PTAB_ENTRY} macro. The ptob can be obtained by using | |
920 | @code{SCM_PTOBNUM} to give an index into the @code{scm_ptobs} | |
921 | global array. | |
922 | ||
923 | @subsubsection Port buffers | |
924 | ||
925 | An input port always has a read buffer and an output port always has a | |
926 | write buffer. However the size of these buffers is not guaranteed to be | |
927 | more than one byte (e.g., the @code{shortbuf} field in @code{scm_port} | |
928 | which is used when no other buffer is allocated). The way in which the | |
929 | buffers are allocated depends on the implementation of the ptob. For | |
930 | example in the case of an fport, buffers may be allocated with malloc | |
931 | when the port is created, but in the case of an strport the underlying | |
932 | string is used as the buffer. | |
933 | ||
934 | @subsubsection The @code{rw_random} flag | |
935 | ||
936 | Special treatment is required for ports which can be seeked at random. | |
937 | Before various operations, such as seeking the port or changing from | |
938 | input to output on a bidirectional port or vice versa, the port | |
85a9b4ed | 939 | implementation must be given a chance to update its state. The write |
9401323e NJ |
940 | buffer is updated by calling the @code{flush} ptob procedure and the |
941 | input buffer is updated by calling the @code{end_input} ptob procedure. | |
942 | In the case of an fport, @code{flush} causes buffered output to be | |
943 | written to the file descriptor, while @code{end_input} causes the | |
944 | descriptor position to be adjusted to account for buffered input which | |
945 | was never read. | |
946 | ||
947 | The special treatment must be performed if the @code{rw_random} flag in | |
948 | the port is non-zero. | |
949 | ||
950 | @subsubsection The @code{rw_active} variable | |
951 | ||
952 | The @code{rw_active} variable in the port is only used if | |
953 | @code{rw_random} is set. It's defined as an enum with the following | |
954 | values: | |
955 | ||
956 | @table @code | |
957 | @item SCM_PORT_READ | |
958 | the read buffer may have unread data. | |
959 | ||
960 | @item SCM_PORT_WRITE | |
961 | the write buffer may have unwritten data. | |
962 | ||
963 | @item SCM_PORT_NEITHER | |
964 | neither the write nor the read buffer has data. | |
965 | @end table | |
966 | ||
967 | @subsubsection Reading from a port. | |
968 | ||
969 | To read from a port, it's possible to either call existing libguile | |
970 | procedures such as @code{scm_getc} and @code{scm_read_line} or to read | |
971 | data from the read buffer directly. Reading from the buffer involves | |
972 | the following steps: | |
973 | ||
974 | @enumerate | |
975 | @item | |
976 | Flush output on the port, if @code{rw_active} is @code{SCM_PORT_WRITE}. | |
977 | ||
978 | @item | |
979 | Fill the read buffer, if it's empty, using @code{scm_fill_input}. | |
980 | ||
981 | @item Read the data from the buffer and update the read position in | |
982 | the buffer. Steps 2) and 3) may be repeated as many times as required. | |
983 | ||
984 | @item Set rw_active to @code{SCM_PORT_READ} if @code{rw_random} is set. | |
985 | ||
986 | @item update the port's line and column counts. | |
987 | @end enumerate | |
988 | ||
989 | @subsubsection Writing to a port. | |
990 | ||
991 | To write data to a port, calling @code{scm_lfwrite} should be sufficient for | |
992 | most purposes. This takes care of the following steps: | |
993 | ||
994 | @enumerate | |
995 | @item | |
996 | End input on the port, if @code{rw_active} is @code{SCM_PORT_READ}. | |
997 | ||
998 | @item | |
999 | Pass the data to the ptob implementation using the @code{write} ptob | |
1000 | procedure. The advantage of using the ptob @code{write} instead of | |
1001 | manipulating the write buffer directly is that it allows the data to be | |
1002 | written in one operation even if the port is using the single-byte | |
1003 | @code{shortbuf}. | |
1004 | ||
1005 | @item | |
1006 | Set @code{rw_active} to @code{SCM_PORT_WRITE} if @code{rw_random} | |
1007 | is set. | |
1008 | @end enumerate | |
1009 | ||
1010 | ||
1011 | @node Port Implementation | |
1012 | @subsection Port Implementation | |
1013 | ||
1014 | This section describes how to implement a new port type in C. | |
1015 | ||
1016 | As described in the previous section, a port type object (ptob) is | |
1017 | a structure of type @code{scm_ptob_descriptor}. A ptob is created by | |
1018 | calling @code{scm_make_port_type}. | |
1019 | ||
1020 | All of the elements of the ptob, apart from @code{name}, are procedures | |
1021 | which collectively implement the port behaviour. Creating a new port | |
1022 | type mostly involves writing these procedures. | |
1023 | ||
1024 | @code{scm_make_port_type} initializes three elements of the structure | |
1025 | (@code{name}, @code{fill_input} and @code{write}) from its arguments. | |
1026 | The remaining elements are initialized with default values and can be | |
1027 | set later if required. | |
1028 | ||
1029 | @table @code | |
1030 | @item name | |
1031 | A pointer to a NUL terminated string: the name of the port type. This | |
1032 | is the only element of @code{scm_ptob_descriptor} which is not | |
1033 | a procedure. Set via the first argument to @code{scm_make_port_type}. | |
1034 | ||
1035 | @item mark | |
1036 | Called during garbage collection to mark any SCM objects that a port | |
1037 | object may contain. It doesn't need to be set unless the port has | |
1038 | @code{SCM} components. Set using @code{scm_set_port_mark}. | |
1039 | ||
1040 | @item free | |
1041 | Called when the port is collected during gc. It | |
1042 | should free any resources used by the port. | |
1043 | Set using @code{scm_set_port_free}. | |
1044 | ||
1045 | @item print | |
1046 | Called when @code{write} is called on the port object, to print a | |
1047 | port description. e.g., for an fport it may produce something like: | |
1048 | @code{#<input: /etc/passwd 3>}. Set using @code{scm_set_port_print}. | |
1049 | ||
1050 | @item equalp | |
1051 | Not used at present. Set using @code{scm_set_port_equalp}. | |
1052 | ||
1053 | @item close | |
1054 | Called when the port is closed, unless it was collected during gc. It | |
1055 | should free any resources used by the port. | |
1056 | Set using @code{scm_set_port_close}. | |
1057 | ||
1058 | @item write | |
1059 | Accept data which is to be written using the port. The port implementation | |
1060 | may choose to buffer the data instead of processing it directly. | |
1061 | Set via the third argument to @code{scm_make_port_type}. | |
1062 | ||
1063 | @item flush | |
1064 | Complete the processing of buffered output data. Reset the value of | |
1065 | @code{rw_active} to @code{SCM_PORT_NEITHER}. | |
1066 | Set using @code{scm_set_port_flush}. | |
1067 | ||
1068 | @item end_input | |
85a9b4ed | 1069 | Perform any synchronization required when switching from input to output |
9401323e NJ |
1070 | on the port. Reset the value of @code{rw_active} to @code{SCM_PORT_NEITHER}. |
1071 | Set using @code{scm_set_port_end_input}. | |
1072 | ||
1073 | @item fill_input | |
1074 | Read new data into the read buffer and return the first character. It | |
1075 | can be assumed that the read buffer is empty when this procedure is called. | |
1076 | Set via the second argument to @code{scm_make_port_type}. | |
1077 | ||
1078 | @item input_waiting | |
1079 | Return a lower bound on the number of bytes that could be read from the | |
1080 | port without blocking. It can be assumed that the current state of | |
1081 | @code{rw_active} is @code{SCM_PORT_NEITHER}. | |
1082 | Set using @code{scm_set_port_input_waiting}. | |
1083 | ||
1084 | @item seek | |
1085 | Set the current position of the port. The procedure can not make | |
1086 | any assumptions about the value of @code{rw_active} when it's | |
1087 | called. It can reset the buffers first if desired by using something | |
1088 | like: | |
1089 | ||
1090 | @example | |
1091 | if (pt->rw_active == SCM_PORT_READ) | |
1092 | scm_end_input (object); | |
1093 | else if (pt->rw_active == SCM_PORT_WRITE) | |
1094 | ptob->flush (object); | |
1095 | @end example | |
1096 | ||
1097 | However note that this will have the side effect of discarding any data | |
1098 | in the unread-char buffer, in addition to any side effects from the | |
1099 | @code{end_input} and @code{flush} ptob procedures. This is undesirable | |
1100 | when seek is called to measure the current position of the port, i.e., | |
1101 | @code{(seek p 0 SEEK_CUR)}. The libguile fport and string port | |
1102 | implementations take care to avoid this problem. | |
1103 | ||
1104 | The procedure is set using @code{scm_set_port_seek}. | |
1105 | ||
1106 | @item truncate | |
1107 | Truncate the port data to be specified length. It can be assumed that the | |
1108 | current state of @code{rw_active} is @code{SCM_PORT_NEITHER}. | |
1109 | Set using @code{scm_set_port_truncate}. | |
1110 | ||
1111 | @end table | |
1112 | ||
1113 | ||
a0e07ba4 NJ |
1114 | @c Local Variables: |
1115 | @c TeX-master: "guile.texi" | |
1116 | @c End: |