stdio.texi

一个C源代码分析器

In practice, it is often easier just to use @code{asprintf}, below.
@end deftypefun

@node Dynamic Output
@subsection Dynamically Allocating Formatted Output

The functions in this section do formatted output and place the results
in dynamically allocated memory.

@comment stdio.h
@comment GNU
@deftypefun int asprintf (char **@var{ptr}, const char *@var{template}, @dots{})
This function is similar to @code{sprintf}, except that it dynamically
allocates a string (as with @code{malloc}; @pxref{Unconstrained
Allocation}) to hold the output, instead of putting the output in a
buffer you allocate in advance.  The @var{ptr} argument should be the
address of a @code{char *} object, and @code{asprintf} stores a pointer
to the newly allocated string at that location.

Here is how to use @code{asprintf} to get the same result as the
@code{snprintf} example, but more easily:

@smallexample
/* @r{Construct a message describing the value of a variable}
   @r{whose name is @var{name} and whose value is @var{value}.} */
char *
make_message (char *name, char *value)
@{
  char *result;
  asprintf (&result, "value of %s is %s", name, value);
  return result;
@}
@end smallexample
@end deftypefun

@comment stdio.h
@comment GNU
@deftypefun int obstack_printf (struct obstack *@var{obstack}, const char *@var{template}, @dots{})
This function is similar to @code{asprintf}, except that it uses the
obstack @var{obstack} to allocate the space.  @xref{Obstacks}.

The characters are written onto the end of the current object.
To get at them, you must finish the object with @code{obstack_finish}
(@pxref{Growing Objects}).@refill
@end deftypefun

@node Variable Arguments Output
@subsection Variable Arguments Output Functions

The functions @code{vprintf} and friends are provided so that you can
define your own variadic @code{printf}-like functions that make use of
the same internals as the built-in formatted output functions.

The most natural way to define such functions would be to use a language
construct to say, ``Call @code{printf} and pass this template plus all
of my arguments after the first five.''  But there is no way to do this
in C, and it would be hard to provide a way, since at the C language
level there is no way to tell how many arguments your function received.

Since that method is impossible, we provide alternative functions, the
@code{vprintf} series, which lets you pass a @code{va_list} to describe
``all of my arguments after the first five.''

Before calling @code{vprintf} or the other functions listed in this
section, you @emph{must} call @code{va_start} (@pxref{Variadic
Functions}) to initialize a pointer to the variable arguments.  Then you
can call @code{va_arg} to fetch the arguments that you want to handle
yourself.  This advances the pointer past those arguments.

Once your @code{va_list} pointer is pointing at the argument of your
choice, you are ready to call @code{vprintf}.  That argument and all
subsequent arguments that were passed to your function are used by
@code{vprintf} along with the template that you specified separately.

In some other systems, the @code{va_list} pointer may become invalid
after the call to @code{vprintf}, so you must not use @code{va_arg}
after you call @code{vprintf}.  Instead, you should call @code{va_end}
to retire the pointer from service.  However, you can safely call
@code{va_start} on another pointer variable and begin fetching the
arguments again through that pointer.  Calling @code{vprintf} does not
destroy the argument list of your function, merely the particular
pointer that you passed to it.

GNU C does not have such restrictions.  You can safely continue to fetch
arguments from a @code{va_list} pointer after passing it to
@code{vprintf}, and @code{va_end} is a no-op.  (Note, however, that
subsequent @code{va_arg} calls will fetch the same arguments which
@code{vprintf} previously used.)

Prototypes for these functions are declared in @file{stdio.h}.
@pindex stdio.h

@comment stdio.h
@comment ANSI
@deftypefun int vprintf (const char *@var{template}, va_list @var{ap})
This function is similar to @code{printf} except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer @var{ap}.
@end deftypefun

@comment stdio.h
@comment ANSI
@deftypefun int vfprintf (FILE *@var{stream}, const char *@var{template}, va_list @var{ap})
This is the equivalent of @code{fprintf} with the variable argument list
specified directly as for @code{vprintf}.
@end deftypefun

@comment stdio.h
@comment ANSI
@deftypefun int vsprintf (char *@var{s}, const char *@var{template}, va_list @var{ap})
This is the equivalent of @code{sprintf} with the variable argument list
specified directly as for @code{vprintf}.
@end deftypefun

@comment stdio.h
@comment GNU
@deftypefun int vsnprintf (char *@var{s}, size_t @var{size}, const char *@var{template}, va_list @var{ap})
This is the equivalent of @code{snprintf} with the variable argument list
specified directly as for @code{vprintf}.
@end deftypefun

@comment stdio.h
@comment GNU
@deftypefun int vasprintf (char **@var{ptr}, const char *@var{template}, va_list @var{ap})
The @code{vasprintf} function is the equivalent of @code{asprintf} with the
variable argument list specified directly as for @code{vprintf}.
@end deftypefun

@comment stdio.h
@comment GNU
@deftypefun int obstack_vprintf (struct obstack *@var{obstack}, const char *@var{template}, va_list @var{ap})
The @code{obstack_vprintf} function is the equivalent of
@code{obstack_printf} with the variable argument list specified directly
as for @code{vprintf}.@refill
@end deftypefun

Here's an example showing how you might use @code{vfprintf}.  This is a
function that prints error messages to the stream @code{stderr}, along
with a prefix indicating the name of the program
(@pxref{Error Messages}, for a description of 
@code{program_invocation_short_name}).

@smallexample
@group
#include <stdio.h>
#include <stdarg.h>

void
eprintf (const char *template, ...)
@{
  va_list ap;
  extern char *program_invocation_short_name;

  fprintf (stderr, "%s: ", program_invocation_short_name);
  va_start (ap, count);
  vfprintf (stderr, template, ap);
  va_end (ap);
@}
@end group
@end smallexample

@noindent
You could call @code{eprintf} like this:

@smallexample
eprintf ("file `%s' does not exist\n", filename);
@end smallexample

In GNU C, there is a special construct you can use to let the compiler
know that a function uses a @code{printf}-style format string.  Then it
can check the number and types of arguments in each call to the
function, and warn you when they do not match the format string.
For example, take this declaration of @code{eprintf}:

@smallexample
void eprintf (const char *template, ...)
        __attribute__ ((format (printf, 1, 2)));
@end smallexample

@noindent
This tells the compiler that @code{eprintf} uses a format string like
@code{printf} (as opposed to @code{scanf}; @pxref{Formatted Input});
the format string appears as the first argument;
and the arguments to satisfy the format begin with the second.
@xref{Function Attributes, , Declaring Attributes of Functions,
gcc.info, Using GNU CC}, for more information.

@node Parsing a Template String
@subsection Parsing a Template String
@cindex parsing a template string

You can use the function @code{parse_printf_format} to obtain
information about the number and types of arguments that are expected by
a given template string.  This function permits interpreters that
provide interfaces to @code{printf} to avoid passing along invalid
arguments from the user's program, which could cause a crash.

All the symbols described in this section are declared in the header
file @file{printf.h}.

@comment printf.h
@comment GNU
@deftypefun size_t parse_printf_format (const char *@var{template}, size_t @var{n}, int *@var{argtypes})
This function returns information about the number and types of
arguments expected by the @code{printf} template string @var{template}.
The information is stored in the array @var{argtypes}; each element of
this array describes one argument.  This information is encoded using
the various @samp{PA_} macros, listed below.

The @var{n} argument specifies the number of elements in the array
@var{argtypes}.  This is the most elements that
@code{parse_printf_format} will try to write.

@code{parse_printf_format} returns the total number of arguments required
by @var{template}.  If this number is greater than @var{n}, then the
information returned describes only the first @var{n} arguments.  If you
want information about more than that many arguments, allocate a bigger
array and call @code{parse_printf_format} again.
@end deftypefun

The argument types are encoded as a combination of a basic type and
modifier flag bits.

@comment printf.h
@comment GNU
@deftypevr Macro int PA_FLAG_MASK
This macro is a bitmask for the type modifier flag bits.  You can write
the expression @code{(argtypes[i] & PA_FLAG_MASK)} to extract just the
flag bits for an argument, or @code{(argtypes[i] & ~PA_FLAG_MASK)} to
extract just the basic type code.
@end deftypevr

Here are symbolic constants that represent the basic types; they stand
for integer values.

@table @code
@comment printf.h
@comment GNU
@item PA_INT
@vindex PA_INT
This specifies that the base type is @code{int}.

@comment printf.h
@comment GNU
@item PA_CHAR
@vindex PA_CHAR
This specifies that the base type is @code{int}, cast to @code{char}.

@comment printf.h
@comment GNU
@item PA_STRING
@vindex PA_STRING
This specifies that the base type is @code{char *}, a null-terminated string.

@comment printf.h
@comment GNU
@item PA_POINTER
@vindex PA_POINTER
This specifies that the base type is @code{void *}, an arbitrary pointer.

@comment printf.h
@comment GNU
@item PA_FLOAT
@vindex PA_FLOAT
This specifies that the base type is @code{float}.

@comment printf.h
@comment GNU
@item PA_DOUBLE
@vindex PA_DOUBLE
This specifies that the base type is @code{double}.

@comment printf.h
@comment GNU
@item PA_LAST
@vindex PA_LAST
You can define additional base types for your own programs as offsets
from @code{PA_LAST}.  For example, if you have data types @samp{foo}
and @samp{bar} with their own specialized @code{printf} conversions,
you could define encodings for these types as:

@smallexample
#define PA_FOO  PA_LAST
#define PA_BAR  (PA_LAST + 1)
@end smallexample
@end table

Here are the flag bits that modify a basic type.  They are combined with
the code for the basic type using inclusive-or.

@table @code
@comment printf.h
@comment GNU
@item PA_FLAG_PTR
@vindex PA_FLAG_PTR
If this bit is set, it indicates that the encoded type is a pointer to
the base type, rather than an immediate value.
For example, @samp{PA_INT|PA_FLAG_PTR} represents the type @samp{int *}.

@comment printf.h
@comment GNU
@item PA_FLAG_SHORT
@vindex PA_FLAG_SHORT
If this bit is set, it indicates that the base type is modified with
@code{short}.  (This corresponds to the @samp{h} type modifier.)

@comment printf.h
@comment GNU
@item PA_FLAG_LONG
@vindex PA_FLAG_LONG
If this bit is set, it indicates that the base type is modified with
@code{long}.  (This corresponds to the @samp{l} type modifier.)

@comment printf.h
@comment GNU
@item PA_FLAG_LONG_LONG
@vindex PA_FLAG_LONG_LONG
If this bit is set, it indicates that the base type is modified with
@code{long long}.  (This corresponds to the @samp{L} type modifier.)

@comment printf.h
@comment GNU
@item PA_FLAG_LONG_DOUBLE
@vindex PA_FLAG_LONG_DOUBLE
This is a synonym for @code{PA_FLAG_LONG_LONG}, used by convention with
a base type of @code{PA_DOUBLE} to indicate a type of @code{long double}.
@end table

@ifinfo
For an example of using these facilitles, see @ref{Example of Parsing}.
@end ifinfo

@node Example of Parsing
@subsection Example of Parsing a Template String

Here is an example of decoding argument types for a format string.  We
assume this is part of an interpreter which contains arguments of type
@code{NUMBER}, @code{CHAR}, @code{STRING} and @code{STRUCTURE} (and
perhaps others which are not valid here).

@smallexample
/* @r{Test whether the @var{