sfio.3

su 的源代码库

Flag \fIspace\fP is ignored if \f5+\fP is specified; otherwise,
it means that if the first character of a signed conversion
is not a sign or if the result is empty, a space will be prepended.

Flag \f50\fP means padding with zeros on the left.

Flag \f5'\fP outputs thousands-separator used by the current locale.
\f5setlocale(3)\fP should have been used to set the desired locale.

Flag \f5#\fP indicates an alternative format processing.
For \f5%o\fP, the first digit is always a zero.
For \f5%x\fP and \f5%X\fP, a non-zero result will have a prefix
\f50x\fP or \f50X\fP. For \f5%e\fP, \f5%E\fP, \f5%f\fP, \f5%g\fP, and \f5%G\fP,
the result always contains a decimal point. For \f5%g\fP and \f5%G\fP,
trailing zeros will not be removed. For \f5%d\fP, \f5%i\fP and \f5%u\fP,
the form is \fIbase#number\fP where \fIbase\fP is the conversion base
and \fInumber\fP is represented by digits for this \fIbase\fP.
For example, a base \f52\fP conversion with \f5%#..2d\fP for \f510\fP
is \f52#1010\fP instead of \f51010\fP as printed with \f5%..2d\fP.
Finally, for \f5%c\fP, bytes will be printed in the C format.
For example, when the ASCII character set is used,
the byte value 10 will be printed as \f5\\n\fP while 255 is printed
as \f5\\377\fP.
.Tp
\f5width\fP:
This defines the width of the printing field. A value to be printed will
be justified and padded if necessary to fill out the field width.
.Tp
\f5precis\fP:
After a first dot appears, an integral value defines a precision.
For floating point value patterns, precision is the number of precision digits.
For \f5%c\fP, precision defines the number of times to repeat the
character being formatted.
For \f5%s\fP, precision defines the maximum number of characters to output.
.Tp
\f5base\fP:
This is defined after exactly two dots have appeared.

For \f5%i\fP, \f5%d\fP, and \f5%u\fP,
\f5base\fP should be an integer value in the inclusive range \f5[2,64]\fP
and defines a conversion base.
If \f5base\fP is not in this range, it is defined to be \f510\fP.
The digits to represent numbers are:

.nf
.ft 5
    01234567890
    abcdefghijklmnopqrstuvwxyz
    ABCDEFGHIJKLMNOPQRSTUVWXYZ @_
.ft 1
.fi

For \f5%s\fP and \f5%c\fP, \f5base\fP defines a separator.
Then, for \f5%s\fP, the input argument is taken to be a NULL-terminated array of strings
while, for \f5%c\fP, this is a null-terminated array of characters.
The strings or characters will be formatted one of a time based
on the usual width and precision rules.
After each formatted string or character, except for the last one,
the separator \f5base\fP is output if it is a non-zero.

There are further restrictions on the syntax of \f5%s\fP and \f5%c\fP when
a separator is defined.
Below are the legitimate sequences for \f5%s\fP and \f5%c\fP after the second dot:

.nf
\f5    s            c\fP
\f5    *s           *c\fP
\f5    \fP\fIz\fP\f5s           \fP\fIz\fP\f5c\fP
.fi

In the first case, no separator is defined so \f5base\fP is set to zero.
In the second case, \f5base\fP is obtained from the argument list.
In the third case, the character \fIz\fP
must be non-alphanumeric and \f5base\fP will be set to this character.

The below example shows both the call and the result
of printing a \f5NULL\fP-terminated array
of three strings \f5apple\fP, \f5orange\fP, and \f5grape\fP:

.nf
.ft 5
    sfprintf(sfstdout,"|%8..:s|",list);
    |   apple:  orange:   grape|
.ft 1
.fi

.Tp
\f5(extfdata)\fP:
This defines a string \f5extfdata\fP
to be passed to the extension function \f5Sffmt_t.extf\fP.
Parentheses shall be balanced.
If \f5extfdata\fP is \f5*\fP, the string is obtained from the argument list.

.PP
.Ss "  int sfscanf(Sfio_t* f, const char* format, ...)"
.Ss "  int sfsscanf(const char* s, const char* format, ...)"
.Ss "  int sfvsscanf(const char* s, const char* format, va_list args)"
.Ss "  int sfvscanf(Sfio_t* f, const char* format, va_list args)"
These functions scan data items.
\f5sfscanf()\fP scans from the input stream \f5f\fP
while \f5sfsscanf()\fP and \f5sfvsscanf()\fP
scan from the null-terminated string \f5s\fP.
\f5sfvscanf()\fP is the underlying primitive that performs the actual scanning.
Item types are determined from patterns in string \f5format\fP.
These functions return
the number of items successfully scanned or \f5-1\fP on error.
.PP
A white space character (blank, tab, or new-line) in \f5format\fP
normally matches a maximal sequence of input white space characters.
However, if the input stream is in \f5SF_LINE\fP mode (see \f5sfset()\fP),
a new-line character only matches white spaces up to an input new-line character.
This is useful to avoid blocking when scanning typed inputs.
.PP
The standard scan patterns are:
\f5i, d, u, o, x, X, p, n, f, e, E, g, G, c, %, s, []\fP and \f5!\fP.
Except for \f5!\fP which shall be described below,
see the ANSI-C specification of \f5fscanf(3)\fP for details on other patterns.
Let \f5z\fP be some pattern type. A formatting pattern is specified as below:

.nf
.ft 5
    %[*][pos$][width][.width.base][(extfdata)][flag]z
.ft 1
.fi

.Tp
\f5pos$\fP:
A pattern can specify which argument in the argument list to use.
This is done via \f5pos$\fP where \f5pos\fP is the argument position.
Arguments are numbered so that the first argument after \f5format\fP is at position 1.
If \f5pos\fP is not specified, the argument following the most recently used one
will be used.
The pattern \f5%!\fP (see below) cannot be used subsequent to a usage of \f5pos$\fP.
.Tp
\f5*:\fP
This discards the corresponding scanned item.
.Tp
\f5width\fP and \f5base\fP:
\f5width\fP defines the maximum number of bytes to scan
and \f5base\fP defines the base of an integral value being scanned.
The `.' (dot) notation also allows specifying a `*' (star) to obtain
the value from the argument list. The below example specifies scanning
4 bytes to obtain the value of an integer in base 10. At the end of scanning,
the variable \f5v\fP should have the value \f51234\fP.

.nf
.ft 5
    sfsscanf("12345678","%.*.*d", 4, 10, &v);
.ft 1
.fi

.Tp
\f5(extfdata)\fP:
This defines a string \f5extfdata\fP
to be passed to the extension function \f5Sffmt_t.extf\fP.
Parentheses shall be balanced.
If \f5extfdata\fP is \f5*\fP, the string is obtained from the argument list.
.Tp
\f5flag:\fP
This is \f5#\fP, \f5I\fP, or some sequence of \f5h\fP, \f5l\fP, and \f5L\fP.

Flag \f5#\fP is significant for pattern \f5%i\fP and \f5%[\fP.
For \f5%i\fP, it means that the \f5#\fP symbol does not have its usual
meaning in an input sequence \f5base#value\fP.
For example, the scanning result of \f5%#i\fP on input \f52#1001\fP is \f52\fP
and the next \f5sfgetc()\fP call will return \f5#\fP.
For \f5%[\fP, if the next character in the input stream does not match
the given scan set of characters, \f5#\fP causes a match to a null string
instead of a failure.

Flag \f5I\fP defines the size or type of the object being formatted.
There are two cases: (1) \f5I\fP by itself and (2) \f5I\fP
followed by either a decimal number or `*'.

In the first case, for integer and floating point patterns,
the object type is taken to be the largest appropriate type
(i.e., one of \f5Sflong_t\fP, \f5Sfulong_t\fP or \f5Sfdouble_t\fP).
For string patterns such as \f5%s\fP, the flag is ignored.

In the second case, a given decimal value would define a size while
`*' would cause the size to be obtained from the argument list.
For string patterns such as \f5%s\fP or \f5%[\fP, this size defines the
length of the buffer to store scanned data.
Specifying a buffer size only limits the amount of data copied into the buffer.
Scanned data beyond the buffer limit will be discarded.
For integer and floating point patterns,
the size is used to select a type from one of the below lists as
indicated by the conversion specifier:

.nf
.ft 5
    Sflong_t, long, int, short
    Sfulong_t, unsigned long, unsigned int, unsigned short
    Sfdouble_t, double, float
.ft 1
.fi

The selection algorithm always matches types from left to right in any given list.
Although selection is generally based on sizes in bytes,
for compatibility with Microsoft-C, the size 64 
is matched with an appropriate type with the same number of bits, if any.
If the given size does not match any of the listed types,
it shall match one of \f5int\fP, \f5unsigned int\fP, and \f5double\fP
as indicated by the formatting pattern.

Below are examples of using the \f5I\fP flag.
The first example scans a 64-bit integer.
The second scans some floating point value
whose size is explicitly computed and given.
The last example scans a string into a buffer with the given size 128.
Note that if the scanned string is longer than 127, only the first 127
bytes shall be copied into the buffer. The rest of the scanned data
shall be discarded.

.nf
.ft 5
     sfscanf(sfstdin,"%I64d", &int64_obj);
     sfscanf(sfstdin,"%I*f", sizeof(float_obj), &float_obj);
     sfscanf(sfstdin,"%I*s", 128, buffer);
.ft 1
.fi

Flags \f5h\fP, \f5l\fP, and \f5L\fP are the ANSI-C conventions
for indicating the type of a scanned element.
For example, \f5%hd\fP means scanning a \f5short int\fP.
The flags \f5ll\fP and \f5L\fP mean respectively scanning an
integer or a floating point value with largest size
(i.e, \f5Sflong_t\fP or \f5Sfdouble_t\fP).
.PP
The \f5%i\fP, \f5%d\fP and \f5%u\fP patterns scan numbers in bases
from \f52\fP to \f564\fP.
\f5%i\fP scans integral values in self-describing formats.
Except for octal, decimal and hexadecimal numbers with the usual formats,
numbers in general bases are assumed to be of the form: \fIbase#value\fP
where \fIbase\fP is a number in base 10 and \fIvalue\fP
is a number in the given base.
For example, \f52#1001\fP is the binary representation of the decimal value \f59\fP.
If \fIbase\fP is \f536\fP or less,
the digits for \fIvalue\fP can be any combination of \f5[0-9], [a-z], [A-Z]\fP
where upper and lower case digits are not distinguishable.
If \fIbase\fP is larger than \f536\fP, the set of digits is:

.nf
.ft 5
    0123456789
    abcdefghijklmnopqrstuvwxyz
    ABCDEFGHIJKLMNOPQRSTUVWXYZ @_
.ft 1
.fi

.PP
.Ss "BUFFERING, SYNCHRONIZATION"
.PP
.Ss "  Void_t* sfsetbuf(Sfio_t* f, Void_t* buf, size_t size)"
This function changed the buffering scheme for the stream \f5f\fP.
The stream will be synchronized before any buffer modification.
If a new buffer is successfully set and the old buffer has not been freed,
\f5sfsetbuf()\fP returns the old buffer. Otherwise, it returns \f5NULL\fP.
After a \f5sfsetbuf()\fP call,
\f5sfvalue()\fP returns the size of the returned buffer.

Sfio attempts to read data in blocks likely to be serviced fast by the file system.
This means block sizes being multiples of a suitable alignment value
(e.g., 512, 1024 or 8192). By default, the alignment value
is computed via some internal mechanism depending on the local platform but
it can also be explicitly set via the call \f5sfsetbuf(f, (Void_t*)f, size)\fP.

In invocations of \f5sfsetbuf()\fP other than the above case,
the \f5size\fP argument is treated as follows:
.Tp
\f5size == SF_UNBOUND\fP:
Sfio will pick a suitable buffer size.
If \f5buf\fP is \f5NULL\fP,
Sfio will also pick a suitable buffering scheme (such as memory mapping.)
If \f5buf\fP is not \f5NULL\fP, its actual value is ignored
but the buffer will be allocated via \f5malloc(3)\fP.
This can be used to avoid memory mapping.
.Tp
\f5size > 0\fP:
This is the suggested size to use for buffering or memory mapping.
If \f5buf\fP is \f5NULL\fP,
Sfio will pick a suitable buffering scheme as discussed above.
If \f5buf\fP is not \f5NULL\fP, then \f5buf\fP and \f5size\fP determine
a buffer of the given size.
.Tp
\f5size == 0\fP:
If \f5buf\fP is \f5NULL\fP, the stream will be unbuffered.
If \f5buf\fP is not \f5NULL\fP,
\f5sfsetbuf()\fP simply returns the stream buffer.
In this case, no attempt will be made to synchronize the stream.

.Ss "  int sfsync(Sfio_t* f)"
This function synchronizes the logical and physical views of stream \f5f\fP.
It returns a negative value for failure and \f50\fP for success.

For a \f5SF_WRITE\fP stream, synchronization means to write out any buffered data.
For a seekable \f5SF_READ\fP file stream,
the physical file position is aligned with the logical stream position and,
if \f5SF_SHARE\fP is on, buffered data is discarded.
If \f5f\fP is \f5NULL\fP, all streams are synchronized.
If \f5f\fP is the base of a stream stack (see \f5sfstack()\fP),
all stacked streams are synchronized.
Note that a stacked stream can only be synchronized this way.
If \f5f\fP is in a pool (see \f5sfpool()\fP) but not being the head,
the pool head is synchronized.

If \f5f\fP has flag \f5SF_IOCHECK\fP, the \f5SF_SYNC\fP event is raised
before and after synchronization. See \f5sfdisc()\fP for details.

.Ss "  int sfpoll(Sfio_t** flist, int n, int timeout)"
This function polls a set of streams to see if I/O operations
can be performed on them without blocking.
This is useful for multiplexing I/O over a set of streams.
If a stream has a discipline, the exception function may be called
before and after the stream is polled (see \f5sfdisc()\fP for details).
After a successful \f5sfpoll()\fP call,
for each ready stream \f5f\fP, \f5sfvalue(f)\fP returns
a bit combination of \f5SF_READ\fP and \f5SF_WRITE\fP to tell which I/O
mode is a