sfio.3

su 的源代码库

executed together in some critical section.
\f5sfmutex()\fP is implicitly used by
all Sfio operations on a stream with the flag \f5SF_MTSAFE\fP.
\f5sfmutex()\fP returns \f50\fP on success and some non-zero value on failure.

Each stream has a lock count which starts at \f50\fP.
When the count is positive, a single thread holds the stream.
Only this thread can further lock or unlock the stream.
A different thread attempting to acquire such a locked stream will suspend
until the lock count returns to \f50\fP.
Each successful locking operation increases the lock count
while each successful unlocking operation decreases it,
thus, allowing nesting of matching lock/unlock operations.

The \f5type\fP argument of \f5sfmutex()\fP takes on the below values:
.Tp
\f5SFMTX_LOCK\fP:
Locking a stream if it is unlocked or increasing the lock count of the stream
if it is already locked by the same thread.
.Tp
\f5SFMTX_TRYLOCK\fP:
This is the non-blocking version of \f5SFMTX_LOCK\fP.
If the stream is already locked by a different thread, \f5sfmutex()\fP will
immediately return with an error status.
.Tp
\f5SFMTX_UNLOCK\fP:
Decreasing the lock count and releasing the stream when the lock count reaches 0.
An attempt to unlock a stream without a previously successful lock may
result in undefined behavior in certain implementations.
The current Sfio implementation returns an error status.
.Tp
\f5SFMTX_CLRLOCK\fP:
Resetting the lock count to \f50\fP and releasing the stream.
As with \f5SFMTX_LOCK\fP,
an attempt to clear the lock count without a previously successful lock
may result in undefined behavior.
.PP
.Ss "INPUT/OUPUT OPERATIONS"
.PP
.Ss "  int sfgetc(Sfio_t* f)"
.Ss "  int sfputc(Sfio_t* f, int c)"
These functions read/write a byte  from/to stream \f5f\fP.
\f5sfgetc()\fP returns the byte read or \f5-1\fP on error.
\f5sfputc()\fP returns \f5c\fP on success and \f5-1\fP on error.

.Ss "  ssize_t sfnputc(Sfio_t* f, int c, size_t n)"
This function attempts to write the byte \f5c\fP to \f5f\fP \f5n\fP times.
It returns the number of bytes actually written or \f5-1\fP on failure.

.Ss "  int sfungetc(Sfio_t* f, int c)"
This function pushes the byte \f5c\fP back into \f5f\fP.
If \f5c\fP matches the byte immediately before the current position in buffered data,
the current position is simply backed up (note the effect on \f5sftell()\fP and
\f5sfseek()\fP). There is no theoretical limit on the number of bytes that
can be pushed back into a stream. Pushed back bytes not part of
buffered data will be discarded on any operation that implies
buffer synchronization.
\f5sfungetc()\fP returns \f5c\fP on success and \f5-1\fP on failure.

.Ss "  Sfulong_t sfgetm(Sfio_t* f, Sfulong_t max)"
.Ss "  int sfputm(Sfio_t* f, Sfulong_t v, Sfulong_t max)"
These functions read and write \f5Sfulong_t\fP values
encoded in a portable format given that the values are at most \f5max\fP.
Portability across a write architecture and a read architecture
requires that the bit order in a byte is the same on both architectures and
the written value is storable in an \f5Sfulong_t\fP on the read architecture.
\f5sfgetm()\fP returns the value read or \f5-1\fP on error.
\f5sfputm()\fP returns the number of bytes written or \f5-1\fP on error.

.Ss "  Sfulong_t sfgetu(Sfio_t* f)"
.Ss "  int sfputu(Sfio_t* f, Sfulong_t v)"
These functions read and write \f5Sfulong_t\fP values
in a compact variable-length portable format.
Portability across a write architecture and a read architecture
requires that the bit order in a byte is the same on both architectures and
the written value is storable in an \f5Sfulong_t\fP on the read architecture.
\f5sfgetu()\fP returns the value read or \f5-1\fP on error.
\f5sfputu()\fP returns the number of bytes written or \f5-1\fP on error.
See also \f5sfulen()\fP.

.Ss "  Sflong_t sfgetl(Sfio_t* f)"
.Ss "  int sfputl(Sfio_t* f, Sflong_t v)"
These functions are similar to \f5sfgetu()\fP and \f5sfputu()\fP
but for reading and writing (signed) \f5Sflong_t\fP values.
See also \f5sfllen()\fP.

.Ss "  Sfdouble_t sfgetd(Sfio_t* f)"
.Ss "  int sfputd(Sfio_t* f, Sfdouble_t v)"
These functions read and write \f5Sfdouble_t\fP values.
In this case, portability depends on the input and output architectures
having the same floating point value representation.
Values are coded and decoded using \f5ldexp(3)\fP and \f5frexp(3)\fP
so they are constrained to the sizes supported by these functions.
See also \f5sfdlen()\fP.

.Ss "  char* sfgetr(Sfio_t* f, int rsc, int type)"
This function reads a record of data ending in the record separator \f5rsc\fP.
After \f5sfgetr()\fP returns, the length of the record even if it is incomplete
can be retrieved with \f5sfvalue()\fP.
\f5sfgetr()\fP returns the record on success and \f5NULL\fP on error.

The \f5type\fP argument is composed of some subset of the below bit flags:
.Tp
\f5SF_STRING\fP:
A null byte will replace the record separator to make the record into a C string.
Otherwise, the record separator is left alone.
.Tp
\f5SF_LOCKR\fP:
Upon successfully obtaining a record \f5r\fP,
the stream will be locked from further access until it is released with
a call \f5sfread(f,r,0)\fP.
.Tp
\f5SF_LASTR\fP:
This should be used only after a failed \f5sfgetr()\fP to retrieve
the last incomplete record. In this case, \f5rsc\fP is ignored.

.Ss "  ssize_t sfputr(Sfio_t* f, const char* s, int rsc)"
This function writes the null-terminated string \f5s\fP to \f5f\fP.
If \f5rsc\fP is non-negative, \f5(unsigned char)rsc\fP is output after the string.
\f5sfputr()\fP returns the number of bytes written or \f5-1\fP on failure.

.Ss "  Sfoff_t sfmove(Sfio_t* fr, Sfio_t* fw, Sfoff_t n, int rsc)"
This function moves objects
from input stream \f5fr\fP to output stream \f5fw\fP.
\f5sfmove()\fP returns the number of objects moved or \f5-1\fP on failure.

An object can be either a byte if the record separator argument
\f5rsc\fP is negative or a record of \f5rsc\fP is non-negative.
In the latter case, a record is incomplete if it does not end in \f5rsc\fP. 
Generally speaking, a stream can have at most one incomplete record.
If \f5n\fP is negative, all complete objects of \f5fr\fP will be moved.
Otherwise, \f5n\fP indicates the number of objects to move.
If either \f5fr\fP or \f5fw\fP is \f5NULL\fP, it acts
as if it is a stream corresponding to \f5/dev/null\fP,
the UNIX device that has no read data and throws away any write data.
For example, the call \f5sfmove(f,(Sfio_t*)0,(Sfoff_t)(-1),'\en')\fP
counts the number of complete lines in stream \f5f\fP.

.Ss "  ssize_t sfread(Sfio_t* f, Void_t* buf, size_t n)"
This function reads up to \f5n\fP bytes from \f5f\fP into buffer \f5buf\fP.
It returns the number of bytes actually read or \f5-1\fP on error.

.Ss "  ssize_t sfwrite(Sfio_t* f, const Void_t* buf, size_t n)"
This function writes \f5n\fP bytes from \f5buf\fP to \f5f\fP.
If \f5f\fP is \f5SF_STRING\fP, and the buffer is not large enough,
an \f5SF_WRITE\fP exception shall be raised.
\f5sfwrite()\fP returns the number of bytes written or \f5-1\fP on failure.

.Ss "  Sfoff_t sfseek(Sfio_t* f, Sfoff_t offset, int type)"
This function sets a new I/O position for \f5f\fP.
It returns the new position or \f5-1\fP on failure.

If the stream is a \f5SF_STRING\fP stream and the new
address is beyond the current buffer extent,
an \f5SF_SEEK\fP exception will be raised (see \f5sfdisc()\fP).

The new position is determined based on \f5offset\fP and
\f5type\fP which is composed from the bit flags:
.Tp
\f50\fP or \f5SEEK_SET\fP:
\f5offset\fP is the desired position.
.Tp
\f51\fP or \f5SEEK_CUR\fP:
\f5offset\fP is relative to the current position (see \f5SF_PUBLIC\fP below).
.Tp
\f52\fP or \f5SEEK_END\fP:
\f5offset\fP is relative to the physical end of file.
.Tp
\f5SF_SHARE\fP:
The stream is treated as if it has the control bit \f5SF_SHARE\fP on.
This implies that a system call seek will be done to ensure that the
location seeking to is valid.
.Tp
\f5SF_PUBLIC\fP:
The stream is treated as if it has the control bit \f5SF_PUBLIC\fP on.
If the physical file position has changed from its last known location,
the current position is taken as the new physical position.
Otherwise, the current position is the logical stream position.

.Ss "  Void_t* sfreserve(Sfio_t* f, ssize_t n, int type)"
This function reserves a data block from the stream \f5f\fP.
It returns the reserved data block on success and \f5NULL\fP on failure.

If \f5f\fP is a \f5SF_READ\fP stream, the data block is a segment of input data.
If \f5f\fP is a \f5SF_WRITE\fP stream, the data block is a buffer
suitable for writing output data.
For consistency, if \f5f\fP is opened with \f5SF_READ|SF_WRITE\fP,
it will normally be treated as if it is a \f5SF_READ\fP stream
(see \f5sfset()\fP for forcing a particular mode) but the returned
buffer can also be written into (more below).
However, it is possible to bias to \f5SF_WRITE\fP when the \f5type\fP
argument is non-negative by adding the \f5SF_WRITE\fP bit \f5type\fP.
In any case, a reserved data block is guaranteed to be valid only until
a future access to the stream \f5f\fP.

When \f5f\fP is \f5SF_READ\fP, \f5SF_SHARE\fP and unseekable,
\f5sfreserve()\fP will attempt to peek at input data without
consuming it. This enables separate processes to share in reading
input from unseekable file descriptors (e.g., pipes or devices).
However, this use of \f5sfreserve()\fP may fail
on certain platforms that do not properly support
peeking on unseekable file descriptors.

After a \f5sfreserve()\fP call, whether or not it succeeds,
\f5sfvalue(f)\fP gives the size of the available data block.
Any partially reserved data block after a failed \f5sfreserve()\fP
call can be obtained in another \f5sfreserve()\fP call with the argument
\f5type\fP being \f5SF_LASTR\fP. The second argument \f5n\fP
to \f5sfreserve()\fP will be ignored in this case.

A \f5sfreserve()\fP call is successful if it can obtain a data block 
of size at least the absolute value of \f5n\fP.
For a \f5SF_READ\fP atream, the argument \f5n\fP is treated as follows:
.Tp
\f5n < 0\fP:
\f5sfreserve()\fP attempts to get \fIat least\fP \f5|n|\fP bytes
into the buffer.
.Tp
\f5n == 0\fP:
If the argument \f5type\fP is \f50\fP,
\f5sfreserve()\fP attempts to get \fIat least\fP \f51\fP byte into the buffer;
otherwise, no attempt will be made to read data into the buffer.
For example, the call \f5sfreserve(f, 0, -1)\fP only returns the buffer status,
i.e., size of existing buffered data and pointer to such data, if any.
The call \f5sfreserve(f, 0, SF_LOCKR)\fP is similar but also locks the stream.
.Tp
\f5n > 0\fP:
\f5sfreserve()\fP will use attempt to get \fIat most\fP \f5n\fP bytes into
the buffer. Further, if \f5type == \f5SF_LOCKR\fP (see below), read attempts
end on a positive amount.

For a successful reservation, the argument \f5type\fP dictates treatment
as follows:
.Tp
\f5type == SF_LASTR\fP:
After a \f5sfreserve()\fP call with \f5type != SF_LOCKR\fP fails,
there may be some left over data not accessible via conventional Sfio calls.
Immediately after such a failed call,
another call to \f5sfreserve\fP with \f5type == SF_LASTR\fP will return any left over
data and also advance the stream I/O position by the amount of returned data.
.Tp
\f5type < 0\fP:
If \f5n > 0\fP, the stream I/O position is advanced by \f5n\fP.
If \f5n < 0\fP, the stream I/O position is advanced by the amount
of available data.
For example, a successful \f5sfreserve(f, -1, -1)\fP call will return a
buffer of data and simultanously advance the stream I/O position by the amount
indicated by \f5sfvalue(f)\fP.
.Tp
\f5type == SF_LOCKR\fP:
The stream I/O position remains unchanged.
In addition, \f5f\fP will be locked from further access.
As appropriate to the stream type (\f5SF_READ\fP, \f5SF_WRITE\fP or both),
\f5f\fP can be unlocked later
with one of \f5sfread(f,rsrv,size)\fP or \f5sfwrite(f,rsrv,size)\fP
where \f5rsrv\fP is the reserved data block and \f5size\fP is the amount of
data to be consumed. For example, if \f5f\fP is a locked \f5SF_READ\fP stream,
the call \f5sfread(f,rsrv,1)\fP will reopen the stream and simultaneously
advance the stream I/O position by \f51\fP.
Finally, a stream opened for both reading and writing
can release the lock with either call (with associated operational semantics!)
For example, the below code reads 10 bytes of data from a stream
opened with both \f5SF_READ\fP and \f5SF_WRITE\fP, modifies the data in place,
then rewrites the new data back to the stream:

.nf
.ft 5
    rsrv = sfreserve(f, 10, 1);
    for(i = 0; i < 10; ++i)
        rsrv[i] = toupper(rsrv[i]);
    sfwrite(f, rsrv, 10);
.ft 1
.fi

.ne 6
.PP
.Ss "DATA FORMATTING"
.PP
Data printing and scanning are done via the
\f5sfprintf()\fP and \f5sfscanf()\fP family of functions.
These functions are similar to their
ANSI-C \f5fprintf()\fP and \f5fscanf()\fP counterparts.
However, the Sfio versions have been extended for both portability and generality.
In particular, a notion of a formatting environment stack is introduced.
Each formatting element on the stack
defines a separate \fIformatting pair\fP of a format specification string,
\f5char* format\fP (the usual second argument in the formatting
functions), and an argument list, \f5va_list args\fP (the third argument
in functions \f5sfvprintf()\fP and \f5sfvscanf()\fP).
A formatting environment element may also specify extension functions
to obtain or assign arguments and to provide new semantics for pattern processing.
To simplify the description below, whenever we talk
about an argument list, unless noted otherwise,
it is understood that this means either the true
argument list when there is no extension function or the action to be taken
by such a function in processing arguments.
The manipulation of the formatting environment stack is done
via the pattern \f5!\fP discussed below.

.Ss "%! and Sffmt_t"
The pattern \f5%!\fP manipulates the formatting environment stack to
(1) change the top environment to a new environment,
(2) stack a new environment on top of the current top,
or (3) pop the top environment.
The bottom of the environment stack always contains a virtual environment with the
original formatting pair and without any extension functions.

The top environment of a stack, say \f5fe\fP, is automatically popped whenever
its format string is completely processed.
In this case, its event-handling function (if any) is called
as \f5(*eventf)(f,SF_FINAL,NIL(Void_t*),fe)\fP.
The top environment
can also be popped by giving an argument \f5NULL\fP to \f5%!\fP
or by returning a negative value in an extension function.
In these cases, the event-handling function is called
as \f5(*eventf)(f,SF_DPOP,form,fe)\fP where \f5form\fP is the remainder
of the format string. A negative return value from the event handling function
will prevent the environment from being popped.

A formatting environment is a structure of type \f5Sffmt_t\fP
which contains the following elements:

.nf
.ft 5