sfio.3

su 的源代码库

    Sffmtext_f   extf;   /* extension processor        */
    Sffmtevent_f eventf; /* event handler              */

    char*        form;   /* format string to stack     */
    va_list      args;   /* corresponding arg list     */
        
    int          fmt;    /* pattern being processed    */
    ssize_t      size;   /* object size                */
    int          flags;  /* formatting control flags   */
    int          width;  /* width of field             */
    int          precis; /* precision required         */
    int          base;   /* conversion base            */

    char*        t_str;  /* extfdata string            */
    int          n_str;  /* length of t_str            */
.ft 1
.fi

The first four elements of \f5Sffmt_t\fP must be defined by the application
before the structure is passed to a formatting function.
The two function fields should not be changed during processing.
Other elements of \f5Sffmt_t\fP are set by the respective formatting function
before it calls the extension function \f5Sffmt_t.extf\fP and, subsequently,
can be modified by this function to redirect formatting or scanning.
For example, consider a call from a \f5sfprintf()\fP function to process an
unknown pattern \f5%t\fP (which we may take to mean ``time'') based on a
formatting environment \f5fe\fP.
\f5fe->extf\fP may reset \f5fe->fmt\fP to `\f5d\fP' upon returing
to cause \f5sfprintf()\fP to process the value being formatted as an integer.

Below are the fields of \f5Sffmt_t\fP:
.Tp
\f5extf\fP:
\f5extf\fP is a function to extend scanning and formatting patterns.
Its usage is discussed below.
.Tp
\f5eventf\fP:
This is a function to process events as discussed earlier.
.Tp
\f5form\fP and \f5args\fP:
This is the formatting pair of a specification string and corresponding argument list.
When an environment \f5fe\fP is being inserted into the stack,
if \f5fe->form\fP is \f5NULL\fP, the top environment is changed to \f5fe\fP
and its associated extension functions
but processing of the current formatting pair continues.
On the other hand, if \f5fe->form\fP is not \f5NULL\fP,
the new environment is pushed onto the stack
so that pattern processing will start with the new formatting pair as well as
any associated extension functions.
During processing, whenever \f5extf\fP is called,
\f5form\fP and \f5args\fP will be set to the current values of
the formatting pair in use.
.Tp
\f5fmt\fP:
This is set to the pattern being processed or one of '.', 'I', '('.
.Tp
\f5size\fP:
This is the size of the object being processed.
.Tp
\f5flags\fP:
This is a collection of bits defining the formatting flags specified for the pattern.
The bits are:

\f5SFFMT_LEFT\fP: Flag \f5-\fP in \f5sfprintf()\fP.

\f5SFFMT_SIGN\fP: Flag \f5+\fP in \f5sfprintf()\fP.

\f5SFFMT_BLANK\fP: Flag \fIspace\fP in \f5sfprintf()\fP.

\f5SFFMT_ZERO\fP: Flag \f50\fP in \f5sfprintf()\fP.

\f5SFFMT_THOUSAND\fP: Flag \f5'\fP in \f5sfprintf()\fP.

\f5SFFMT_LONG\fP: Flag \f5l\fP in \f5sfprintf()\fP and \f5sfscanf()\fP.

\f5SFFMT_LLONG\fP: Flag \f5ll\fP in \f5sfprintf()\fP and \f5sfscanf()\fP.

\f5SFFMT_SHORT\fP: Flag \f5h\fP in \f5sfprintf()\fP and \f5sfscanf()\fP.

\f5SFFMT_LDOUBLE\fP: Flag \f5L\fP in \f5sfprintf()\fP and \f5sfscanf()\fP.

\f5SFFMT_IFLAG\fP: flag \f5I\fP in \f5sfprintf()\fP and \f5sfscanf()\fP.

\f5SFFMT_ALTER\fP: Flag \f5#\fP in \f5sfprintf()\fP and \f5sfscanf()\fP.

\f5SFFMT_SKIP\fP: Flag \f5*\fP in \f5sfscanf()\fP.

\f5SFFMT_ARGPOS\fP: This indicates argument processing for \f5pos$\fP.

\f5SFFMT_VALUE\fP: This is set by \f5fe->extf\fP
to indicate that it is returning a value to be formatted or
the address of an object to be assigned.

.Tp
\f5width\fP:
This is the field width.
.Tp
\f5precis\fP:
This is the precision.
.Tp
\f5base\fP:
This is the conversion base.
.Tp
\f5t_str\fP and \f5n_str\fP:
This is the type string and its size.

.Ss "  int (*Sffmtext_f)(Sfio_t* f, Void_t* v, Sffmt_t* fe)"
This is the type of the extension function \f5fe->extf\fP to process
patterns and arguments.
Arguments are always processed in order and
\f5fe->extf\fP is called exactly once per argument.
Note that, when \f5pos$\fP (below) is not used anywhere in a format string,
each argument is used exactly once per a corresponding pattern.
In that case, \f5fe->extf\fP is called 
as soon as the pattern is recognized and before any scanning or formatting.
On the other hand, when \f5pos$\fP is used in a format string,
an argument may be used multiple times.
In this case, all arguments shall be processed in order
by calling \f5fe->extf\fP exactly once per argument before any pattern processing.
This case is signified by the flag \f5SFFMT_ARGPOS\fP in \f5fe->flags\fP.

In addition to the predefined formatting patterns and other application-defined
patterns, \f5fe->extf\fP may be called with \f5fe->fmt\fP being one
of `\f5(\fP' (left parenthesis), `\f5.\fP' (dot), and `\f5I\fP'.

The left parenthesis requests a string to be used as the \f5extfdata\fP string discussed below.
In this case, upon returning, \f5fe->extf\fP should set the \f5fe->size\fP field
to be the length of the string or a negative value to indicate a null-terminated string.

The `\f5I\fP' requests an integer to define the object size.

The dot requests an integer for width, precision, base, or a separator.
In this case, the \f5fe->size\fP field will indicate how many dots have appeared
in the pattern specification. Note that, if the actual conversion pattern is 'c' or 's',
the value \f5*form\fP will be one of these characters.
.Tp
\f5f\fP:
This is the input/output stream in the calling formatting function.
During a call to \f5fe->extf\fP, the stream shall be unlocked
so that \f5fe->extf\fP can read from or write to it as appropriate.
.Tp
\f5v\fP:
For both \f5sfscanf()\fP and \f5sfprintf()\fP functions,
\f5v\fP points to a location suitable for storing any scalars or pointers.
On return, \f5fe->extf\fP treats \f5v\fP as discussed below.
.Tp
\f5fe\fP:
This is the current formatting environment.
.PP
The return value \f5rv\fP of \f5fe->extf\fP directs further processing.
There are two cases.
When \f5pos$\fP is present, a negative return value means to ignore \f5fe\fP
in further argument processing while a non-negative return value is treated
as the case \f5rv == 0\fP below.
When \f5pos$\fP is not present, \f5fe->extf\fP is called per argument
immediately before pattern processing and its return values are treated
as below:
.Tp
\f5rv < 0:\fP
The environment stack is immediately popped.
.Tp
\f5rv == 0:\fP
The extension function has not consumed (in a scanning case) or
output (in a printing case) data out of or into the given stream \f5f\fP.
The fields \f5fmt\fP, \f5flags\fP, \f5size\fP,
\f5width\fP, \f5precis\fP and \f5base\fP of \f5fe\fP
shall direct further processing.

For \f5sfprintf()\fP functions, if \f5fe->flags\fP
has the bit \f5SFFMT_VALUE\fP,
\f5fe->extf\fP should have set \f5*v\fP to the value to be processed;
otherwise, a value should be obtained from the argument list.
Likewise, for \f5sfscanf()\fP functions,
\f5SFFMT_VALUE\fP means that
\f5*v\fP should have a suitable address; otherwise,
an address to assign value should be obtained from the argument list.

When \f5pos$\fP is present,
if \f5fe->extf\fP changes \f5fe->fmt\fP, this pattern shall be used regardless of
the pattern defined in the format string. On the other hand, if \f5fe->fmt\fP
is unchanged by \f5fe->extf\fP, the pattern in the format string is used.
In any case, the effective pattern should be one of the standardly defined pattern.
Otherwise, it shall be treated as unmatched.
.Tp
\f5rv > 0:\fP
The extension function has accessed the stream \f5f\fP
to the extent of \f5rv\fP bytes.
Processing of the current pattern ceases except that,
for scanning functions, if \f5fe->flags\fP does not contain
the bit \f5SFFMT_SKIP\fP, the assignment count shall increase by 1.

.Ss "void va_copy(va_list to, va_list fr)"
This macro function portably copies the argument list \f5fr\fP to
the argument list \f5to\fP. It should be used to set the field \f5Sffmt_t.args\fP.

.Ss "long sffmtversion(Sffmt_t* fe, int type)"
This macro function initializes
the formatting environment \f5fe\fP with a version number if \f5type\fP is
non-zero. Otherwise, it returns the current value of the version number of \f5fe\fP.
This is useful for applications to find out
when the format of the structure \f5Sffmt_t\fP changes.
Note that the version number corresponds to the Sfio version number
which is defined in the macro value \f5SFIO_VERSION\fP.

.Ss "  int sfprintf(Sfio_t* f, const char* format, ...)"
.Ss "  char* sfprints(const char* format, ...)"
.Ss "  ssize_t sfaprints(char** sp, const char* format, ...);"
.Ss "  ssize_t sfvaprints(char** sp, const char* format, va_list args);"
.Ss "  int sfsprintf(char* s, int n, const char* format, ...)"
.Ss "  int sfvsprintf(char* s, int n, const char* format, va_list args)"
.Ss "  int sfvprintf(Sfio_t* f, const char* format, va_list args)"
These functions format output data.
\f5sfprintf()\fP and \f5sfvprintf()\fP write to output stream \f5f\fP.
\f5sfsprintf()\fP and \f5sfvsprintf()\fP write to buffer \f5s\fP
which is of size \f5n\fP.
\f5sfprints()\fP constructs output in some Sfio-defined buffer.
\f5sfaprints()\fP and \f5sfvaprints()\fP are similar to \f5sfprints()\fP
but they return the constructed string in  \f5*sp\fP and expect this string
to be freed by the caller when no longer needed.
\f5sfvprintf()\fP is the underlying primitive for the other functions.
Except for \f5sfprints()\fP
which returns a null-terminated string or \f5NULL\fP,
other functions return the number of output bytes or \f5-1\fP on failure.

The length of string constructed by \f5sfprints()\fP, \f5sfsprintf()\fP, or
\f5sfvsprintf()\fP can be retrieved by \f5sfslen()\fP.
.PP
The standard patterns are:
\f5n, s, c, %, h, i, d, p, u, o, x, X, g, G, e, E, f\fP and \f5!\fP.
Except for \f5!\fP which shall be described below,
see the ANSI-C specification of \f5fprintf(3)\fP for details on the other patterns.
Let \f5z\fP be some pattern type. A formatting pattern is defined as below:

.nf
.ft 5
    %[pos$][flag][width][.precision[.base]][(extfdata)]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.
Doing so may cause unexpected behaviors.
.Tp
\f5flag\fP:
The flag characters are
\f5h\fP, \f5hh\fP, \f5l\fP, \f5ll\fP, \f5L\fP, \f5I\fP, \f5j\fP, \f5t\fP, \f5z\fP,
\f5\-\fP, \f5+\fP, \fIspace\fP, \f50\fP, \f5'\fP and \f5#\fP.

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 conversion specifiers \f5s\fP and \f5c\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.
Then, if the conversion specifier is \f5s\fP, this size defines the
length of the string or strings being formatted (see the discussion of \f5base\fP below).
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 defined by the formatting pattern.

Below are a few examples of using the \f5I\fP flag.
The first example prints an \f5Sflong_t\fP integer.
This example is actually not portable and
only works on platforms where \f5sizeof(Sflong_t)\fP is 8.
The second example shows how to that portably.
The third example specifies printing a string of length 16.
This length shall be used regardless of whether or not the given string
is shorter or longer than 16.
The last example shows the use of the pattern \f5%n\fP to assign the amount
of data already output into a \f5short\fP integer \f5n_output\fP.

.nf
.ft 5
    sfprintf(sfstdout,"%I8d", Sflong_obj);
    sfprintf(sfstdout,"%I*d", sizeof(Sflong_obj), Sflong_obj);
    sfprintf(sfstdout,"%I*s", 16, s);
    sfprintf(sfstdout,"%d%I*n", 1001, sizeof(short), &n_output);
.ft 1
.fi

Flags \f5h\fP, \f5l\fP, and \f5L\fP are the ANSI-C conventions to
select the types of input objects.
For example, \f5%hd\fP indicates a \f5short int\fP
while \f5%ld\fP indicates a \f5long int\fP.

Flag \f5hh\fP addresses the byte value types, i.e., \f5char\fP and \f5unsigned char\fP.

Flags \f5z\fP, \f5t\fP and \f5j\fP address respectively
the types \f5size_t\fP, \f5ptrdiff_t\fP and \f5Sflong_t\fP.

Flags \f5ll\fP and \f5L\fP address respectively
the largest integer and floating value types, i.e.,
\f5Sfulong_t\fP, \f5Sflong_t\fP, and \f5Sfdouble_t\fP.

Flag \f5-\fP left-justifies data within the field (otherwise, right-justification).

Flag \f5+\fP means that a signed conversion will always begin with a plus or minus sign.