Interface to AT&T's Safe/Fast I/O Library.
From the sfio page:
<blockquote> 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. </blockquote>
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).
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.
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[procedure] (sfio-stream? x)
Returns #t if x is an sfio-stream and #f otherwise.[procedure] (sfio-stream-handle sf)
Returns the C pointer of an SFIO stream or #f if that pointer is NULL.
Opening and closing streams[constant] sfio:stdin
These are the SFIO streams associated with the standard input, standard output and standard error descriptors.[procedure] (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.[procedure] (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.[procedure] (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.[procedure] (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.[procedure] (sfio:close sf)
Closes an sfio-stream. Returns #t on success and #f if an error occurs.
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.