Eggs Unlimited

sfio

Description:

Interface to AT&T's Safe/Fast I/O Library.

Sfio is a library for managing I/O streams. It provides functionality similar to that of Stdio, the ANSI C Standard I/O library, but via a distinct interface that is more powerful, robust and efficient. Below are some desirable attributes of Sfio:

Streams can be safely used in multi-threaded applications. Since thread-safety can be expensive, the library allows an application to choose when a stream should be thread-safe.
The library uses a buffering strategy that allows correct sharing of file descriptors across streams and/or processes.
An adaptive buffering algorithm is used to enhance I/O performance in a wide range of applications from sequential to random data access.
Data formatting functions are supported by efficient algorithms for integer and floating point value conversions. In addition, applications can define or redefine formatting directives.
I/O disciplines can be used to pre/post-process read/write data from/to streams,
Streams can be stacked for recursive processing of nested streams,
Stream can be pooled for automatic stream synchronization as I/O operations are switched from stream to stream.
Operations are provided to perform zero-copy stream I/O.
Lines and records of any length can be read from any stream.

The current version of the Chicken extension has some limitations:

formatted i/o is not supported
i/o disciplines are not supported
thread safety features are not supported

You must, of course, have AT&T's SFIO library installed for this extension to compile. Edit the sfio.setup file to specify the correct locations of SFIO's lib and include directories (the defaults are /usr/local/lib and /usr/local/include).

Author:

Category 5

Version:

0.1

Usage:

(require-extension sfio)

Download:

sfio.egg

Documentation:

This extension provides a more-or-less direct interface to all SFIO library functions except those associated with the unsupported functionality noted above. Most of the procedures provided by this extension have the same names as the SFIO library functions with the sf prefix replaced by sfio:. Thus, for example, the equivalent of sfread in this extension is sfio:read.

The sfio: procedures are relatively thin wrappers around their C library equivalents. They do, however, perform basic argument type checking (unless the extension is compiled as unsafe). This extension defines the disjoint type sfio-stream, used to represent SFIO stream objects.

Most of these procedures return #f in the event of an error. In situations where an SFIO routine accepts a NULL argument, #f may be supplied.

Flags

Some SFIO C functions accept an integer argument that is treated as a bitmask of flags. The Scheme equivalents accept a list of symbols (possibly an implicit list in the form of a rest argument). The valid flag symbols are:

    string
    read
    write
    appendwr
    line
    share
    public
    malloc
    static
    iocheck
    whole
    mtsafe
    ;; records
    lockr
    lastr
    ;; for sfio:seek
    seek-set
    seek-cur
    seek-end

Not all flags are valid in all contexts that accept a flag-list. See the SFIO documentation for details on which flags are valid in a given context.

Scheme-specific procedures

(sfio-stream? x): Returns #t if x is an sfio-stream and #f otherwise.
(sfio-stream-handle sf): Returns the C pointer of an SFIO stream or #f if that pointer is NULL.

Opening and closing streams

sfio:stdin sfio:stdout sfio:stderr: These are the SFIO streams associated with the standard input, standard output and standard error descriptors.
(sfio:new f buf size fd . flags): This procedure creates or renews a stream. The f argument is an sfio-stream or #f. The buf argument should be a non-immediate string or #f. The size and fd arguments should be integers. Any remaining arguments should be valid flag symbols as explained in the Flags section.

This procedure returns an sfio-stream or #f.
(sfio:open sf str mode): Opens a file or string and returns an sfio-stream. The sf argument is treated as in sfio:new. The str argument is a string that specifies the filename to open or the string to open as a stream if the s mode specifier is present. The mode argument is a string consisting of mode specifier characters that describes how to open the stream; see the SFIO documentation for details.

This procedure returns an sfio-stream or #f.
(sfio:popen sf cmd mode): Opens a stream whose input and output are connected to the subprocess specified by the string cmd, executed using /bin/sh or the interpreter specified by the SHELL environment variable. The sf argument is either #f or a stream to renew; see sfio:new. The mode argument is a string containing one or more of the characters r w +.

This procedure returns an sfio-stream or #f.
(sfio:tmp size): Creates and returns a stream for temporary data. If size is #f the stream is a pure string stream. If size is zero, the stream is a pure file stream. Otherwise the stream is first created as a string stream but when its buffer grows larger than size a temporary file is created.

This procedure returns an sfio-stream or #f.
(sfio:close sf): Closes an sfio-stream. Returns #t on success and #f if an error occurs.

Input/output

(sfio:getc sf) (sfio:putc sf c): These procedures read or write a byte from or to a stream sf. The c argument to sfio:putc may be either an integer or a character.

sfio:getc returns the byte read (as an integer) on success and #f otherwise. sfio:putc returns #t on success and #f otherwise.
(sfio:nputc sf c n): This procedure attempts to write the byte c (which may be an integer or character) to the stream sf n times. It returns the number of bytes actually written or #f.
(sfio:ungetc sf c): This procedure pushes the byte c (which may be an integer or character) back into sf. It returns #t on success and #f otherwise.
(sfio:getm sf max) (sfio:putm sf v max): These procedures read and write single unsigned-long values encoded in a portable format, given that the values are at most max. The max and v arguments are integers. See the SFIO documentation for details.

sfio:getm returns the value read or #f. sfio:putm returns the number of bytes written or #f.
(sfio:getu sf) (sfio:putu sf v): These procedures read and write unsigned-long values in a compact variable-length portable format. See the SFIO documentation for details.

sfio:getu returns the value read or #f. sfio:putu returns the number of bytes written or #f.
(sfio:getl sf) (sfio:putl sf v): These procedures are similar to sfio:getu and sfio:putu but are for reading and writing signed long values.
(sfio:getd sf) (sfio:putd sf v): These procedures are similar to sfio:getu and sfio:putu but are for reading and writing double values.
(sfio:getr sf sep . type-flags): This procedure reads a record of data ending in the record separator sep (which may be an integer or a character). Any remaining arguments should be valid flag symbols as listed in the Flags section and explained in the SFIO documentation.

This procedure returns the record (as a string) or #f.
(sfio:putr sf s sep): This procedure writes the string s to the stream sf and also writes the byte sep if it is a character or an integer that is not negative. It returns the number of bytes written or #f.
(sfio:move sfr sfw n sep): This procedure moves objects from input stream sfr to output stream sfw. An object is either a record (if sep is a character or nonnegative integer) or a byte. The n argument specifies the number of objects to move: if it is negative, all of sfr will be moved. If either sfr or sfw is #f it acts as if it were a stream corresponding to /dev/null.

This procedure returns the number of objects written or #f.
(sfio:read sf n): Attemps to read n bytes from sf and returns either a string consisting of the bytes actually read or #f if an error occurs.
(sfio:write sf str): Attempts to write the bytes of the string str to sf. Returns the number of bytes actually written or #f if an error occurs.
(sfio:seek sf offset . type-flags): This procedure sets a new I/O position for the stream sf based on the integer offset and the provided type-flags (see the Flags section).

Returns the new offset or #f.
(sfio:reserve sf n . type-flags): This procedure reserves a data block of size n from the stream sf. See the SFIO documentation for details.

Returns a C pointer to the data block or #f.

Buffering and synchronization

(sfio:setbuf sf buf size): This procedure queries or changes the buffering scheme for the stream sf. See the SFIO documentation for details.

If a new buffer is successfully set and the old buffer has not been freed, this procedure returns a machine pointer to the old buffer. Otherwise #f is returned.
(sfio:sync sf): This procedure synchronizes the logical and physical views of the stream sf. It returns #t on success and #f otherwise.
(sfio:poll sflist timeout-ms): This procedure accepts a list of sfio-stream objects and an integer specifying a timeout in milliseconds. It returns the number of ready streams or #f if an error occurs. The sfio:value procedure can be used to test streams for read/write readiness.
(sfio:pool sf poolsf mode): This procedure manipulates pools of streams. It returns either an sfio-stream or #f. See the SFIO documentation for details.
(sfio:purge sf): This procedure discards all buffered data for the stream sf unless it is a string stream. Returns #t on success and #f otherwise.

Stream control

(sfio:resize sf size): This procedure resizes the stream sf so that its extent is size, which should be an integer. If sf is a file stream, ftruncate(2) will be used to set the file size. When the size of a stream is increased, the new space will be zero-filled.

Returns #t on success and #f otherwise.
(sfio:set sf flag-list set?): This procedure sets control flags for the stream sf. The flag-list argument should be a list of zero or more of the following symbols:
read write iocheck line share public malloc static
If the set? argument is #f, an attempt is made to clear the flags specified in flag-list. Otherwise an attempt is made to set them.

Returns #f on failure and otherwise an integer representing the current set of flags. See the SFIO documentation for details.
(sfio:setfd sf fd): This procedure changes the file descriptor for the stream sf to that specified by the integer fd. See the SFIO documentation for details. Returns #f on failure or the new file descriptor.
(sfio:stack sfbase sftop): This procedure stacks or unstacks streams. See the SFIO documentation for details. Returns an sfio-stream or #f on failure.
(sfio:swap sf1 sf2): This procedure swaps the contents of sf1 with sf2. If sf2 is #f a new stream is constructed as a duplicate of sf1. Returns sf2 or the sf1 duplicate on success and #f on failure.

Stream information

(sfio:size sf): This procedure returns the size of the stream sf. If sf is not seekable or its size cannot be determined, #f is returned.
(sfio:tell sf): This procedure returns the current I/O position for sf. If sf is not seekable, it returns the number of bytes read from or written to sf.
(sfio:value sf): This procedure returns the string or buffer length for sfio:reserve, sfio:setbuf and sfio:getr. It is used to provide information in some other cases as well; see the SFIO documentation for details.
(sfio:fileno sf): This procedure returns the file descriptor associated with sf.
(sfio:stacked? sf): This procedure returns #t if sf has been stacked and #f otherwise.
(sfio:eof? sf) (sfio:error? sf) (sfio:clrerr sf): These procedures check for an EOF condition, check for an error condition, or clear an EOF/error condition on a stream sf, respectively. Note that EOF and error conditions are also cleared automatically on an I/O operation.

These functions return #t or #f.
(sfio:clrlock sf): This procedure restores the stream sf to a normal state. This means clearing locks and possibly throwing away unprocessed data. See the SFIO documentation for details. Returns an integer representing the current set of flags for sf.

Miscellaneous operations

(sfio:slen): This procedure returns the length of a string just constructed with sfio:sprintf or sfio:prints.
(sfio:ulen v) (sfio:llen v) (sfio:dlen v): These procedures return the number of bytes required to encode the value v by sfio:putu, sfio:putl and sfio:putd.
(sfio:peek-read fd n sep tm action): This procedure acts directly on the file descriptor fd. It performs a combination of peeking on incoming data and a timeout read. The argument n specifies the number of bytes to read. The argument sep, which may be a character or an integer, specifies a record separator if it is greater than zero. If tm is nonnegative it specifies the number of milliseconds to wait for incoming data. See the SFIO documentation for the meaning of the integer action and for further details.

Returns the number of bytes received, zero on an EOF condition, or #f in the event of an error.

Examples:

(require-extension sfio)

(define sfio:readline
  (lambda (sf)
    (sfio:getr sf #\newline)))

(define f1 (sfio:open #f "some-text-file.txt" "r"))

(time
  (let loop ((ln (sfio:readline f1)))
    (if (not ln) 'done
        (loop (sfio:readline f1)))))

(sfio:close f1)

License:

Copyright (c) 2004, Category 5
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer. Redistributions in
  binary form must reproduce the above copyright notice, this list of
  conditions and the following disclaimer in the documentation and/or other
  materials provided with the distribution. Neither the name of the author
  nor the names of its contributors may be used to endorse or promote
  products derived from this software without specific prior written
  permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

back