sfio.3

su 的源代码库

.PP
.Ss "  Sfoff_t"
This defines an integral type suitable to address
the largest possible file extent.
.PP
.Ss "  Sfulong_t, Sflong_t, Sfdouble_t"
These are respectively the largest
unsigned integer, signed integer, and floating point value types on the local platform.
.PP
.Ss "  Sfio_t"
This defines the type of a stream handle.
.PP
.Ss "  Sfdisc_t"
.Ss "  ssize_t (*Sfread_f)(Sfio_t*, Void_t*, size_t, Sfdisc_t*)"
.Ss "  ssize_t (*Sfwrite_f)(Sfio_t*, const Void_t*, size_t, Sfdisc_t*)"
.Ss "  Sfoff_t (*Sfseek_f)(Sfio_t*, Sfoff_t, int, Sfdisc_t*)"
.Ss "  int (*Sfexcept_f)(Sfio_t*, int, Void_t*, Sfdisc_t*)"
\f5Sfdisc_t\fP defines a stream discipline structure.
\f5Sfread_f\fP, \f5Sfwrite_f\fP and \f5Sfseek_f\fP are the types
of discipline functions to replace the system calls:
\f5read(2)\fP, \f5write(2)\fP and \f5lseek(2)\fP.
\f5Sfexcept_f\fP is the type of an event-handling function.
See \f5sfdisc()\fP for more details.
.PP
.Ss "  Sffmt_t"
.Ss "  int (*Sffmtext_f)(Sfio_t*, Void_t*, Sffmt_t*)"
.Ss "  int (*Sffmtevent_f)(Sfio_t*, int, Void_t*, Sffmt_t*)"
\f5Sffmt_t\fP defines a formatting environment that can be used
to extend scanning and printing in the \f5sfprint()/sfscanf()\fP
functions. \f5Sffmtext_f\fP and \f5Sffmtevent_f\fP define the types
of extension functions definable in \f5Sffmt_t\fP.
See \f5Sffmt_t\fP below for more details.
.PP
.Ss "  SFIO_VERSION"
This is a macro value of type \f5long int\fP that defines
the current version number of Sfio. For example, the Sfio2000's
version number is \f520000515L\fP
(which also indicates its latest version date: 05/15/2000).

.Ss "BIT FLAGS"
A number of bit flags control stream operations.
They are set either at stream initialization or by calling \f5sfset()\fP.
Following are the flags:
.Tp
\f5SF_STRING\fP:
The stream is memory-based.
.Tp
\f5SF_READ\fP, \f5SF_WRITE\fP, \f5SF_APPENDWR\fP (\f5SF_APPEND\fP):
Flags \f5SF_READ\fP and \f5SF_WRITE\fP indicate readability and writability.
Flag \f5SF_APPENDWR\fP asserts that the stream is a file opened in append mode
(see \f5open(2)\fP and \f5fcntl(2)\fP)
so that data is always output at the end of file.
On systems without direct support for append mode,
Sfio uses \f5lseek(2)\fP or its discipline replacement
to approximate this behavior.
.Tp
\f5SF_LINE\fP:
The stream is line-oriented.
For a \f5SF_WRITE\fP stream,
this means that buffered data is flushed
whenever a new-line character, \f5\en\fP, is output.
For a \f5SF_READ\fP stream, \f5SF_LINE\fP is only
significant during calls to functions in the \f5sfscanf()\fP family.
\f5SF_LINE\fP is set on initialization of
any stream representing a terminal device.
.Tp
\f5SF_SHARE\fP, \f5SF_PUBLIC\fP:
Flag \f5SF_SHARE\fP means that the underlying file descriptor
is shared by independent entities (for example, multiple processes).

For a seekable file stream, \f5SF_SHARE\fP means that
the logical stream and the physical file positions will be made the same
before a system call to perform physical I/O.
There are different possibilities.
If \f5SF_PUBLIC\fP is not set,
the physical file position is made equal to the logical stream position.
If \f5SF_PUBLIC\fP is set, there are two cases.
If the physical file position has changed from its last known position,
the logical stream position is made equal to the new physical file position.
Finally, if the physical file location remains the same as its last known position,
the physical file position is made the same as the logical stream position.

For an unseekable stream (e.g., pipes or terminal devices), if possible,
\f5SF_SHARE\fP means that
the block and record I/O operations (\f5sfread()\fP, \f5sfwrite()\fP, \f5sfmove()\fP,
\f5sfgetr()\fP, \f5sfputr()\fP, \f5sfreserve()\fP, \f5sfscanf()\fP
and \f5sfvprintf()\fP) will ensure:
(1) after each writing operation, the stream is synchronized and
(2) each reading operation only reads the requested amount.
Note, however, that (2) is not always possible
without proper OS facilities such as \f5recv(2)\fP or \f5streamio(4)\fP.

A standard stream that is seekable will be initialized with \f5SF_SHARE|SF_PUBLIC\fP.
.Tp
\f5SF_MALLOC\fP:
The stream buffer was obtained via \f5malloc(3)\fP
and can be reallocated or freed.
.Tp
\f5SF_STATIC\fP:
The stream structure should not be freed when closed (\f5sfclose()\fP).
This flag is used by an applications that allocate their own
stream structures. Such applications must use the header file \f5sfio_t.h\fP
instead of \f5sfio.h\fP.
.Tp
\f5SF_IOCHECK\fP:
If the stream has a discipline exception handler,
exceptions will be raised in \f5sfsync()\fP, \f5sfpurge()\fP
or before a system call \f5read(2)\fP or \f5write(2)\fP (see \f5sfdisc()\fP).
.Tp
\f5SF_WHOLE\fP:
This flag guarantees that data written in any single \f5sfwrite()\fP or
\f5sfputr()\fP call will always be output as a whole to the output device.
This is useful in certain applications (e.g., networking) where a complex object
must be output without being split in different system calls.
Note that the respective stream still buffers data as much as the buffer can accomodate.
.Tp
\f5SF_MTSAFE\fP:
This flag indicates that the respective stream may be accessed by more than one threads.
A mutex lock will be used to ensure that only one thread at a time can access
the stream. Note that this flag can only be set at stream opening time
(see \f5sfopen()\fP, \f5sfpopen()\fP and \f5sfnew()\fP).
Certain fast macro functions such as \f5sfgetc()\fP and \f5sfputc()\fP will
no longer behave as macros. Thus, an application that requires such fast macro functions
should leave \f5SF_MTSAFE\fP off and performs explicit locking with \f5sfmutex()\fP.
.Tp
\f5SF_IOINTR\fP:
This flag indicates that I/O system calls should not be resumed 
after being interrupted by signals. It is useful for 
aborting I/O operations on such interruptions. Note, however,
than certain operating systems (e.g., BSD Unix systems) may automatically
resume interrupted system calls outside the scope of the library. On such systems,
\f5SF_IOINTR\fP will be ineffective.

.PP
.Ss "OPENING/CLOSING STREAMS"
.PP
.Ss "  Sfio_t* sfnew(Sfio_t* f, Void_t* buf, size_t size, int fd, int flags)"
This function creates or renews a stream.
It returns the new stream on success and \f5NULL\fP on error.
.Tp
\f5f\fP:
If \f5f\fP is \f5NULL\fP, a new stream is created.
Otherwise, \f5f\fP is reused.
In this case, if \f5flags\fP does not have \f5SF_EOF\fP,
\f5f\fP shall be closed via \f5sfclose()\fP before being reused.
During a stream renewal, buffer, pool and discipline stack are preserved.
Note that, except for \f5SF_STATIC\fP streams,
renewing a stream already closed will result in undefined behavior.
.Tp
\f5buf\fP, \f5size\fP:
These determine a buffering scheme.
See \f5sfsetbuf()\fP for more details.
.Tp
\f5fd\fP:
If \f5SF_STRING\fP is specified in \f5flags\fP, this is ignored.
Otherwise, \f5fd\fP is a file descriptor (e.g., from \f5open(2)\fP)
to use for raw data I/O.
Note that Sfio supports unseekable file descriptors
opened for both read and write, e.g., sockets.
.Tp
\f5flags\fP:
This is composed from \f5SF_EOF\fP and
bit values defined in the \fBBIT FLAGS\fP section.
Note, in particular, that a multi-threaded application should
set the bit \f5SF_MTSAFE\fP to protect the new stream from
being simultaneously accessed by multiple threads.

.Ss "  Sfio_t* sfopen(Sfio_t* f, const char* string, const char* mode)"

If \f5string\fP is \f5NULL\fP,
\f5f\fP is a file stream and
\f5mode\fP does not imply a string stream,
\f5sfopen()\fP changes the modes of \f5f\fP according to \f5mode\fP.
In this case, \f5sfopen()\fP returns \f5f\fP on success and \f5NULL\fP on error.
This somewhat unusual usage of \f5sfopen()\fP is good for
resetting certain predefined modes in standard streams including
\fItext/binary\fP and \fIappend\fP that are inherited from some parent process.
Note also that \f5SF_READ\fP and \f5SF_WRITE\fP can only be reset if the stream
is not yet initialized.

\f5sfopen()\fP is normally used to create a new stream or renew a stream.
In this case, it returns the new stream on success and \f5NULL\fP on error.
Below are the meanings of the arguments:
.Tp
\f5f\fP:
This is treated as in \f5sfnew()\fP.
.Tp
\f5string\fP:
This is a file name or a string to perform I/O on.
See above for when this is \f5NULL\fP.
.Tp
\f5mode\fP:
This is composed from the set of letters \f5{s, r, w, +, a, b, t, x, m, u}\fP.
When conflicting options are present in the same \f5mode\fP string,
the last one will take effect.

\f5s\fP specifies opening a string stream.
\f5string\fP can be a null-terminated string or \f5NULL\fP.
Specifying \f5s\fP alone is equivalent to specifying \f5sr\fP.
If \f5s\fP is not specified, \f5string\fP defines a file name.

\f5r\fP and \f5w\fP specify read and write modes.
Write mode creates and/or truncates the given file to make an empty file.
The \f5+\fP modifier indicates that the stream is opened for both read and write.

\f5a\fP specifies append mode, i.e., data is always output at end of file.

\f5b\fP and \f5t\fP specify binary and text modes.

\f5x\fP specifies exclusive mode, i.e.,
a file opened for writing should not already exist.

\f5m\fP specifies that the stream needs to be protected from
simultaneous accesses by multiple threads.
This turns on the bit flag \f5SF_MTSAFE\fP.

\f5u\fP specifies that the stream is guaranteed to be accessed
by only one thread at a time. The bit flag \f5SF_MTSAFE\fP is left off.
The absence of option \f5m\fP is the same as the presence of option \f5u\fP.

.Ss "  Sfio_t* sfpopen(Sfio_t* f, const char* cmd, const char* mode)"
This function opens a stream that corresponds to the coprocess \f5cmd\fP.
The argument \f5mode\fP should be composed from \f5r\fP, \f5w\fP, and \f5+\fP.
The argument \f5f\fP, if not \f5NULL\fP, is a stream to be renewed (see \f5sfnew()\fP).
\f5sfpopen()\fP returns the new stream or \f5NULL\fP on error.

The standard input/output of \f5cmd\fP
is connected to the application via a pipe if the stream is opened for writing/reading.
If the stream is opened for both reading and writing,
there will be two different associated file descriptors, one for each type of I/O
(note the effect on \f5sffileno()\fP).

On opening a coprocess for writing (i.e., \f5mode\fP contains \f5w\fP or \f5+\fP),
the signal handler for \f5SIGPIPE\fP in the parent application
will be set to \f5SIG_IGN\fP if it is \f5SIG_DFL\fP at that time.
This protects the parent application from being accidentally killed
on writing to a coprocess that closes its reading end.
Applications that need to detect such write errors should use
disciplines and exception handlers (see \f5sfdisc()\fP).

The command \f5cmd\fP
is executed by an \fIinterpreter\fP which is either \f5/bin/sh\fP
or an executable command defined by the environment variable \f5SHELL\fP.
In either case, the interpreter is invoked with 2 arguments, respectively \f5-c\fP
and the given command \f5cmd\fP. When the interpreter is \f5/bin/sh\fP or
\f5/bin/ksh\fP, \f5sfpopen()\fP may execute the command \f5cmd\fP itself
if there are no shell meta-characters in \f5cmd\fP.

.Ss "  Sfio_t* sftmp(size_t size)"
This function creates a stream for temporary data.
It returns the new stream or \f5NULL\fP on error.

A stream created by \f5sftmp()\fP can be completely or partially memory-resident.
If \f5size\fP is \f5SF_UNBOUND\fP, the stream is a pure string stream.
If \f5size\fP 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 \f5size\fP or on any attempt to change disciplines,
a temporary file is created.
Two environment variables, \f5TMPPATH\fP and \f5TMPDIR\fP,
direct where temporary files are created.
\f5TMPPATH\fP, if defined,
specifies a colon-separated set of directories to be
used in a round-robin fashion to create files.
If \f5TMPPATH\fP is undefined,
\f5TMPDIR\fP can be used to specify a single directory to create files.
If neither of \f5TMPPATH\fP and \f5TMPDIR\fP are defined, \f5/tmp\fP is used.

.Ss "  int sfclose(Sfio_t* f)"
This function closes the stream \f5f\fP and frees its resources.
\f5SF_STATIC\fP should be used if the stream space is to be preserved.
If \f5f\fP is the base of a stream stack (see \f5sfstack()\fP),
all streams on the stack are closed.
If \f5f\fP is a \f5sfpopen\fP-stream,
\f5sfclose()\fP waits until the associated command terminates
and returns its exit status.
\f5sfclose()\fP returns \f5-1\fP for failure and \f50\fP for success.

\f5SF_READ|SF_SHARE\fP and \f5SF_WRITE\fP streams
are synchronized before closing (see \f5sfsync()\fP).
If \f5f\fP has disciplines,
their exception handlers will be called twice.
The first exception handler call has the \f5type\fP argument as one of
\f5SF_CLOSING\fP or \f5SF_NEW\fP (see \f5sfdisc()\fP.)
The latter, \f5SF_NEW\fP is used when a stream is being closed via \f5sfnew()\fP
so that it can be renewed.
The second call uses \f5type\fP as \f5SF_FINAL\fP
and is done after all closing operations have succeeded but before
the stream itself is deallocated.
In either case, if the exception handler returns a negative value,
\f5sfclose()\fP will immediately return this value.
If the exception handler returns a positive value,
\f5sfclose()\fP will immediately return a zero value.

.PP
.Ss "THREAD SAFETY"
.PP
The libraries \f5libsfio.a\fP and \f5libstdio.a\fP (providing binary
compatibility to Stdio-based code) only support uni-threaded code.
Multi-threaded applications should link with
\f5libsfio-mt.a\fP and \f5libstdio-mt.a\fP.
When this is done, certain platforms may require additional
thread libraries for linkage. For example, Linux, Irix and Solaris
require \f5-lpthread\fP while HPUX requires \f5-lcma\fP.
Aside from linkage differences, the Sfio API remains identical in all cases.

Note that unlike Stdio streams which are in thread-safe mode by default.
Sfio streams can be opened in either uni-threaded or multi-threaded mode.
A uni-threaded stream is more efficient than a multi-threaded one.
For example, functions such as \f5sfgetc()\fP and \f5sfputc()\fP
remain as macro or inline functions for a uni-threaded stream while
they will act as full function calls in a multi-threaded case.
The three standard streams \f5sfstdin/sfstdout/sfstderr\fP
are in multi-threaded mode by default
(however, see \f5sfopen()\fP for how this may be changed).
Other Sfio streams are normally opened uni-threaded unless
the flag \f5SF_MTSAFE\fP or the option \f5m\fP were specified.
Stdio-based code can also make a Stdio stream uni-threaded by
using the option \f5u\fP when opening a file.

.PP
.Ss "int sfmutex(Sfio_t* f, int type)"
This function acquires or releases a mutex
(mutually exclusive) lock on the stream \f5f\fP.
It can be used by a thread to delineate  a sequence of I/O operations