source: project/sfio/sfio.html @ 1

Last change on this file since 1 was 1, checked in by azul, 15 years ago

Import everything.

File size: 18.5 KB
Line 
1<html>
2<head>
3  <title>Eggs Unlimited - sfio</title>
4  <style><!--
5  dd { margin-bottom: 20px }
6  -->
7  </style> 
8</head>
9<body>
10<font face="Arial, Helvetica">
11
12<center><img src="egg.jpg"></center>
13<center><a href="index.html">back</a></center>
14
15<h2>sfio</h2>
16
17<h3>Description:</h3>
18Interface to AT&amp;T's Safe/Fast I/O Library.
19
20<p> From the <a href="http://www.research.att.com/sw/tools/sfio/">sfio page</a>:
21
22<blockquote>
23Sfio is a library for managing I/O streams. It provides functionality
24similar to that of Stdio, the ANSI C Standard I/O library, but via a
25distinct interface that is more powerful, robust and efficient. Below are
26some desirable attributes of Sfio:
27
28<ul>
29<li> Streams can be safely used in multi-threaded applications. Since
30thread-safety can be expensive, the library allows an application to choose
31when a stream should be thread-safe.
32
33<li> The library uses a buffering strategy that allows correct sharing of file
34descriptors across streams and/or processes.
35
36<li> An adaptive buffering algorithm is used to enhance I/O performance in a wide
37range of applications from sequential to random data access.
38
39<li> Data formatting functions are supported by efficient algorithms for integer
40and floating point value conversions. In addition, applications can define
41or redefine formatting directives.
42
43<li> I/O disciplines can be used to pre/post-process read/write data from/to
44streams,
45
46<li> Streams can be stacked for recursive processing of nested streams,
47
48<li> Stream can be pooled for automatic stream synchronization as I/O operations
49are switched from stream to stream.
50
51<li> Operations are provided to perform zero-copy stream I/O.
52
53<li> Lines and records of any length can be read from any stream.
54</ul>
55</blockquote>
56
57<p> The current version of the Chicken extension has some limitations:
58<ul>
59  <li> formatted i/o is not supported
60  <li> i/o disciplines are not supported
61  <li> thread safety features are not supported
62</ul>
63
64<p> You must, of course, have AT&amp;T's SFIO library installed for this
65extension to compile.  Edit the <tt>sfio.setup</tt> file to specify the
66correct locations of SFIO's <tt>lib</tt> and <tt>include</tt> directories
67(the defaults are <tt>/usr/local/lib</tt> and <tt>/usr/local/include</tt>).
68
69<h3>Author:</h3>
70Category 5
71
72<h3>Version:</h3>
730.1
74
75<h3>Usage:</h3> 
76<p> <tt>(require-extension sfio)</tt>
77
78<h3>Download:</h3>
79<p> <a href="sfio.egg">sfio.egg</a>
80
81<h3>Documentation:</h3>
82
83<p> This extension provides a more-or-less direct interface to all SFIO
84library functions except those associated with the unsupported functionality
85noted above.  Most of the procedures provided by this extension have the
86same names as the SFIO library functions with the <tt>sf</tt> prefix
87replaced by <tt>sfio:</tt>.  Thus, for example, the equivalent of
88<tt>sfread</tt> in this extension is <tt>sfio:read</tt>.
89
90<p> The <tt>sfio:</tt> procedures are relatively thin wrappers around their
91C library equivalents.  They do, however, perform basic argument type
92checking (unless the extension is compiled as <tt>unsafe</tt>).  This
93extension defines the disjoint type <tt>sfio-stream</tt>, used to represent
94SFIO stream objects.
95
96<p> Most of these procedures return <tt>#f</tt> in the event of an error.
97In situations where an SFIO routine accepts a NULL argument, <tt>#f</tt> may
98be supplied.
99
100<h4>Flags</h4>
101
102<p> Some SFIO C functions accept an integer argument that is treated as a
103bitmask of flags.  The Scheme equivalents accept a list of symbols (possibly
104an implicit list in the form of a rest argument).  The valid flag symbols
105are:
106<pre>
107    string
108    read
109    write
110    appendwr
111    line
112    share
113    public
114    malloc
115    static
116    iocheck
117    whole
118    mtsafe
119    ;; records
120    lockr
121    lastr
122    ;; for sfio:seek
123    seek-set
124    seek-cur
125    seek-end
126</pre>
127
128<p> Not all flags are valid in all contexts that accept a flag-list.  See
129the SFIO documentation for details on which flags are valid in a given
130context.
131
132<h4>Scheme-specific procedures</h4>
133
134<dl>
135<dt><tt> (sfio-stream? <i>x</i>) </tt></dt>
136<dd> Returns <tt>#t</tt> if <tt><i>x</i></tt> is an sfio-stream and
137<tt>#f</tt> otherwise.</dd>
138
139<dt><tt> (sfio-stream-handle <i>sf</i>) </tt></dt>
140<dd> Returns the C pointer of an SFIO stream or <tt>#f</tt> if that pointer
141is NULL. </dd>
142</dl>
143
144<h4>Opening and closing streams</h4>
145
146<dl>
147<dt><tt> sfio:stdin  <br>
148         sfio:stdout <br>
149         sfio:stderr </tt></dt>
150<dd> These are the SFIO streams associated with the standard input, standard
151output and standard error descriptors.</dd>
152
153<dt><tt> (sfio:new f buf size fd . flags) </tt></dt>
154<dd> This procedure creates or renews a stream.  The <tt>f</tt> argument is
155an sfio-stream or <tt>#f</tt>.  The <tt>buf</tt> argument should be a
156non-immediate string or <tt>#f</tt>.  The <tt>size</tt> and <tt>fd</tt>
157arguments should be integers.  Any remaining arguments should be valid flag
158symbols as explained in the <b>Flags</b> section.
159<br><br>
160This procedure returns an sfio-stream or <tt>#f</tt>.
161</dd>
162
163<dt><tt> (sfio:open sf str mode) </tt></dt>
164
165<dd> Opens a file or string and returns an sfio-stream.  The <tt>sf</tt>
166argument is treated as in <tt>sfio:new</tt>.  The <tt>str</tt> argument is a
167string that specifies the filename to open or the string to open as a stream
168if the <tt>s</tt> mode specifier is present.  The <tt>mode</tt> argument is
169a string consisting of mode specifier characters that describes how to open
170the stream; see the SFIO documentation for details.
171<br><br>
172This procedure returns an sfio-stream or <tt>#f</tt>.
173</dd>
174
175<dt><tt> (sfio:popen sf cmd mode) </tt></dt>
176
177<dd> Opens a stream whose input and output are connected to the subprocess
178specified by the string <tt>cmd</tt>, executed using <tt>/bin/sh</tt> or the
179interpreter specified by the <tt>SHELL</tt> environment variable.  The
180<tt>sf</tt> argument is either <tt>#f</tt> or a stream to renew; see
181<tt>sfio:new</tt>.  The <tt>mode</tt> argument is a string containing one or
182more of the characters <tt>r w +</tt>.
183<br><br>
184This procedure returns an sfio-stream or <tt>#f</tt>.
185</dd>
186
187<dt><tt> (sfio:tmp size) </tt></dt>
188
189<dd> Creates and returns a stream for temporary data.  If <tt>size</tt> is
190<tt>#f</tt> the stream is a pure string stream.  If <tt>size</tt> is zero,
191the stream is a pure file stream.  Otherwise the stream is first created as
192a string stream but when its buffer grows larger than <tt>size</tt> a
193temporary file is created.
194<br><br>
195This procedure returns an sfio-stream or <tt>#f</tt>.
196</dd>
197
198<dt><tt> (sfio:close sf) </tt></dt>
199
200<dd> Closes an sfio-stream.  Returns <tt>#t</tt> on success and <tt>#f</tt>
201if an error occurs.</dd>
202</dl>
203
204<h4>Input/output</h4>
205
206<dl>
207<dt><tt> (sfio:getc sf) <br>
208         (sfio:putc sf c) </tt></dt>
209
210<dd> These procedures read or write a byte from or to a stream <tt>sf</tt>.
211The <tt>c</tt> argument to <tt>sfio:putc</tt> may be either an integer or a
212character.
213<br><br>
214<tt>sfio:getc</tt> returns the byte read (as an integer) on success and
215<tt>#f</tt> otherwise.  <tt>sfio:putc</tt> returns <tt>#t</tt> on success
216and <tt>#f</tt> otherwise. </dd>
217
218<dt><tt> (sfio:nputc sf c n) </tt></dt>
219
220<dd> This procedure attempts to write the byte <tt>c</tt> (which may be an
221integer or character) to the stream <tt>sf</tt> <tt>n</tt> times.  It
222returns the number of bytes actually written or <tt>#f</tt></dd>
223
224<dt><tt> (sfio:ungetc sf c) </tt></dt>
225
226<dd> This procedure pushes the byte <tt>c</tt> (which may be an integer or
227character) back into <tt>sf</tt>.  It returns <tt>#t</tt> on success and
228<tt>#f</tt> otherwise. </dd>
229
230<dt><tt> (sfio:getm sf max) <br>
231         (sfio:putm sf v max) </tt></dt>
232
233<dd> These procedures read and write single unsigned-long values encoded in
234a portable format, given that the values are at most <tt>max</tt>.  The
235<tt>max</tt> and <tt>v</tt> arguments are integers.  See the SFIO
236documentation for details.
237<br><br>
238<tt>sfio:getm</tt> returns the value read or <tt>#f</tt>.
239<tt>sfio:putm</tt> returns the number of bytes written or <tt>#f</tt>. </dd>
240
241<dt><tt> (sfio:getu sf) <br>
242         (sfio:putu sf v) </tt></dt>
243
244<dd> These procedures read and write unsigned-long values in a compact
245variable-length portable format.  See the SFIO documentation for details.
246<br><br>
247<tt>sfio:getu</tt> returns the value read or <tt>#f</tt>.
248<tt>sfio:putu</tt> returns the number of bytes written or <tt>#f</tt>. </dd>
249
250<dt><tt> (sfio:getl sf) <br>
251         (sfio:putl sf v) </tt></dt>
252
253<dd> These procedures are similar to <tt>sfio:getu</tt> and
254<tt>sfio:putu</tt> but are for reading and writing signed long values. </dd>
255
256<dt><tt> (sfio:getd sf) <br>
257         (sfio:putd sf v) </tt></dt>
258
259<dd> These procedures are similar to <tt>sfio:getu</tt> and
260<tt>sfio:putu</tt> but are for reading and writing double values. </dd>
261
262<dt><tt> (sfio:getr sf sep . type-flags) </tt></dt>
263
264<dd> This procedure reads a record of data ending in the record separator
265<tt>sep</tt> (which may be an integer or a character).  Any remaining
266arguments should be valid flag symbols as listed in the <b>Flags</b> section
267and explained in the SFIO documentation.
268<br><br>
269This procedure returns the record (as a string) or <tt>#f</tt>. </dd>
270
271<dt><tt> (sfio:putr sf s sep) </tt></dt>
272
273<dd> This procedure writes the string <tt>s</tt> to the stream <tt>sf</tt>
274and also writes the byte <tt>sep</tt> if it is a character or an integer
275that is not negative.  It returns the number of bytes written or
276<tt>#f</tt>. </dd>
277
278<dt><tt> (sfio:move sfr sfw n sep) </tt></dt>
279
280<dd> This procedure moves objects from input stream <tt>sfr</tt> to output
281stream <tt>sfw</tt>.  An object is either a record (if <tt>sep</tt> is a
282character or nonnegative integer) or a byte.  The <tt>n</tt> argument
283specifies the number of objects to move: if it is negative, all of
284<tt>sfr</tt> will be moved.  If either <tt>sfr</tt> or <tt>sfw</tt> is
285<tt>#f</tt> it acts as if it were a stream corresponding to
286<tt>/dev/null</tt>.
287<br><br>
288This procedure returns the number of objects written or <tt>#f</tt>. </dd>
289
290<dt><tt> (sfio:read sf n) </tt></dt>
291
292<dd> Attemps to read <tt>n</tt> bytes from <tt>sf</tt> and returns either
293a string consisting of the bytes actually read or <tt>#f</tt> if an error
294occurs. </dd>
295
296<dt><tt> (sfio:write sf str) </tt></dt>
297
298<dd> Attempts to write the bytes of the string <tt>str</tt> to <tt>sf</tt>.
299Returns the number of bytes actually written or <tt>#f</tt> if an error
300occurs. </dd>
301
302<dt><tt> (sfio:seek sf offset . type-flags) </tt></dt>
303
304<dd> This procedure sets a new I/O position for the stream <tt>sf</tt> based
305on the integer <tt>offset</tt> and the provided <tt>type-flags</tt> (see the
306<b>Flags</b> section).
307<br><br>
308Returns the new offset or <tt>#f</tt>. </dd>
309
310<dt><tt> (sfio:reserve sf n . type-flags) </tt></dt>
311
312<dd> This procedure reserves a data block of size <tt>n</tt> from the stream
313<tt>sf</tt>.  See the SFIO documentation for details.
314<br><br>
315Returns a C pointer to the data block or <tt>#f</tt>. </dd>
316</dl>
317
318<h4>Buffering and synchronization</h4>
319
320<dl>
321<dt><tt> (sfio:setbuf sf buf size) </tt></dt>
322
323<dd> This procedure queries or changes the buffering scheme for the stream
324<tt>sf</tt>.  See the SFIO documentation for details.
325<br><br>
326If a new buffer is successfully set and the old buffer has not been freed,
327this procedure returns a machine pointer to the old buffer.  Otherwise
328<tt>#f</tt> is returned. </dd>
329
330<dt><tt> (sfio:sync sf) </tt></dt>
331
332<dd> This procedure synchronizes the logical and physical views of the
333stream <tt>sf</tt>.  It returns <tt>#t</tt> on success and <tt>#f</tt>
334otherwise. </dd>
335
336<dt><tt> (sfio:poll sflist timeout-ms) </tt></dt>
337
338<dd> This procedure accepts a list of sfio-stream objects and an integer
339specifying a timeout in milliseconds.  It returns the number of ready
340streams or <tt>#f</tt> if an error occurs.  The <tt>sfio:value</tt>
341procedure can be used to test streams for read/write readiness. </dd>
342
343<dt><tt> (sfio:pool sf poolsf mode) </tt></dt>
344
345<dd> This procedure manipulates pools of streams.  It returns either an
346sfio-stream or <tt>#f</tt>.  See the SFIO documentation for details. </dd>
347
348<dt><tt> (sfio:purge sf) </tt></dt>
349
350<dd> This procedure discards all buffered data for the stream <tt>sf</tt>
351unless it is a string stream.  Returns <tt>#t</tt> on success and
352<tt>#f</tt> otherwise. </dd>
353</dl>
354
355<h4>Stream control</h4>
356
357<dl>
358<dt><tt> (sfio:resize sf size) </tt></dt>
359
360<dd> This procedure resizes the stream <tt>sf</tt> so that its extent is
361<tt>size</tt>, which should be an integer.  If <tt>sf</tt> is a file stream,
362<tt>ftruncate(2)</tt> will be used to set the file size.  When the size of a
363stream is increased, the new space will be zero-filled.
364<br><br>
365Returns <tt>#t</tt> on success and <tt>#f</tt> otherwise. </dd>
366
367<dt><tt> (sfio:set sf flag-list set?) </tt></dt>
368
369<dd> This procedure sets control flags for the stream <tt>sf</tt>.  The
370<tt>flag-list</tt> argument should be a list of zero or more of the
371following symbols:
372
373<blockquote>
374  <tt>read write iocheck line share public malloc static</tt>
375</blockquote>
376
377If the <tt>set?</tt> argument is <tt>#f</tt>, an attempt is made to clear
378the flags specified in <tt>flag-list</tt>.  Otherwise an attempt is made to
379set them.
380<br><br>
381Returns <tt>#f</tt> on failure and otherwise an integer representing the
382current set of flags.  See the SFIO documentation for details. </dd>
383
384<dt><tt> (sfio:setfd sf fd) </tt></dt>
385
386<dd> This procedure changes the file descriptor for the stream <tt>sf</tt>
387to that specified by the integer <tt>fd</tt>.  See the SFIO documentation
388for details.  Returns <tt>#f</tt> on failure or the new file descriptor. </dd>
389
390<dt><tt> (sfio:stack sfbase sftop) </tt></dt>
391
392<dd> This procedure stacks or unstacks streams.  See the SFIO documentation
393for details.  Returns an sfio-stream or <tt>#f</tt> on failure. </dd>
394
395<dt><tt> (sfio:swap sf1 sf2) </tt></dt>
396
397<dd> This procedure swaps the contents of <tt>sf1</tt> with <tt>sf2</tt>.
398If <tt>sf2</tt> is <tt>#f</tt> a new stream is constructed as a duplicate of
399<tt>sf1</tt>.  Returns <tt>sf2</tt> or the <tt>sf1</tt> duplicate on success
400and <tt>#f</tt> on failure. </dd>
401</dl>
402
403<h4>Stream information</h4>
404
405<dl>
406<dt><tt> (sfio:size sf) </tt></dt>
407
408<dd> This procedure returns the size of the stream <tt>sf</tt>.  If
409<tt>sf</tt> is not seekable or its size cannot be determined, <tt>#f</tt> is
410returned. </dd>
411
412<dt><tt> (sfio:tell sf) </tt></dt>
413
414<dd> This procedure returns the current I/O position for <tt>sf</tt>.  If
415<tt>sf</tt> is not seekable, it returns the number of bytes read from or
416written to <tt>sf</tt>. </dd>
417
418<dt><tt> (sfio:value sf) </tt></dt>
419
420<dd> This procedure returns the string or buffer length for
421<tt>sfio:reserve</tt>, <tt>sfio:setbuf</tt> and <tt>sfio:getr</tt>.  It is
422used to provide information in some other cases as well; see the SFIO
423documentation for details. </dd>
424
425<dt><tt> (sfio:fileno sf) </tt></dt>
426
427<dd> This procedure returns the file descriptor associated with
428<tt>sf</tt>. </dd>
429
430<dt><tt> (sfio:stacked? sf) </tt></dt>
431
432<dd> This procedure returns <tt>#t</tt> if <tt>sf</tt> has been stacked and
433<tt>#f</tt> otherwise. </dd>
434
435<dt><tt> (sfio:eof? sf)   <br>
436         (sfio:error? sf) <br>
437         (sfio:clrerr sf) </tt></dt>
438
439<dd> These procedures check for an EOF condition, check for an error
440condition, or clear an EOF/error condition on a stream <tt>sf</tt>,
441respectively.  Note that EOF and error conditions are also cleared
442automatically on an I/O operation.
443<br><br>
444These functions return <tt>#t</tt> or <tt>#f</tt>. </dd>
445
446<dt><tt> (sfio:clrlock sf) </tt></dt>
447
448<dd> This procedure restores the stream <tt>sf</tt> to a normal state.  This
449means clearing locks and possibly throwing away unprocessed data.  See the
450SFIO documentation for details.  Returns an integer representing the current
451set of flags for <tt>sf</tt>. </dd>
452</dl>
453
454<h4>Miscellaneous operations</h4>
455
456<dl>
457<dt><tt> (sfio:slen) </tt></dt>
458
459<dd> This procedure returns the length of a string just constructed with
460<tt>sfio:sprintf</tt> or <tt>sfio:prints</tt>. </dd>
461
462<dt><tt> (sfio:ulen v) <br>
463         (sfio:llen v) <br>
464         (sfio:dlen v) </tt></dt>
465
466<dd> These procedures return the number of bytes required to encode the
467value <tt>v</tt> by <tt>sfio:putu</tt>, <tt>sfio:putl</tt> and
468<tt>sfio:putd</tt>. </dd>
469
470<dt><tt> (sfio:peek-read fd n sep tm action) </tt></dt>
471
472<dd> This procedure acts directly on the file descriptor <tt>fd</tt>.  It
473performs a combination of peeking on incoming data and a timeout read.  The
474argument <tt>n</tt> specifies the number of bytes to read.  The argument
475<tt>sep</tt>, which may be a character or an integer, specifies a record
476separator if it is greater than zero.  If <tt>tm</tt> is nonnegative it
477specifies the number of milliseconds to wait for incoming data.  See the
478SFIO documentation for the meaning of the integer <tt>action</tt> and for
479further details.
480<br><br>
481Returns the number of bytes received, zero on an EOF condition, or
482<tt>#f</tt> in the event of an error. </dd>
483
484</dl>
485
486<h3>Examples:</h3>
487
488<pre>
489(require-extension sfio)
490
491(define sfio:readline
492  (lambda (sf)
493    (sfio:getr sf #\newline)))
494
495(define f1 (sfio:open #f "some-text-file.txt" "r"))
496
497(time
498  (let loop ((ln (sfio:readline f1)))
499    (if (not ln) 'done
500        (loop (sfio:readline f1)))))
501
502(sfio:close f1)
503</pre>
504
505<h3>License:</h3>
506<pre>
507Copyright (c) 2004, Category 5
508All rights reserved.
509
510Redistribution and use in source and binary forms, with or without
511modification, are permitted provided that the following conditions are met:
512
513  Redistributions of source code must retain the above copyright notice,
514  this list of conditions and the following disclaimer. Redistributions in
515  binary form must reproduce the above copyright notice, this list of
516  conditions and the following disclaimer in the documentation and/or other
517  materials provided with the distribution. Neither the name of the author
518  nor the names of its contributors may be used to endorse or promote
519  products derived from this software without specific prior written
520  permission.
521
522THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
523AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
524IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
525ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
526LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
527CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
528SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
529INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
530CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
531ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
532POSSIBILITY OF SUCH DAMAGE.
533</pre>
534
535<hr><a href="index.html">back</a>
536
537</font>
538</body>
539</html>
Note: See TracBrowser for help on using the repository browser.