library_11.html

Linux程序员的工作手册

</PRE>
<P>
prints <SAMP>`0x'</SAMP> followed by a hexadecimal number--the address of the
string constant <CODE>"testing"</CODE>.  It does not print the word
<SAMP>`testing'</SAMP>.
<P>
You can supply the <SAMP>`-'</SAMP> flag with the <SAMP>`%p'</SAMP> conversion to
specify left-justification, but no other flags, precision, or type
modifiers are defined.
<P>
The <SAMP>`%n'</SAMP> conversion is unlike any of the other output conversions.
It uses an argument which must be a pointer to an <CODE>int</CODE>, but
instead of printing anything it stores the number of characters printed
so far by this call at that location.  The <SAMP>`h'</SAMP> and <SAMP>`l'</SAMP> type
modifiers are permitted to specify that the argument is of type
<CODE>short int *</CODE> or <CODE>long int *</CODE> instead of <CODE>int *</CODE>, but no
flags, field width, or precision are permitted.
<P>
For example,
<P>
<PRE>
int nchar;
printf ("%d %s%n\n", 3, "bears", &#38;nchar);
</PRE>
<P>
prints:
<P>
<PRE>
3 bears
</PRE>
<P>
and sets <CODE>nchar</CODE> to <CODE>7</CODE>, because <SAMP>`3 bears'</SAMP> is seven 
characters.
<P>
The <SAMP>`%%'</SAMP> conversion prints a literal <SAMP>`%'</SAMP> character.  This
conversion doesn't use an argument, and no flags, field width,
precision, or type modifiers are permitted.
<P>
<H3><A NAME="SEC135" HREF="library_toc.html#SEC135" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC135">Formatted Output Functions</A></H3>
<P>
This section describes how to call <CODE>printf</CODE> and related functions.
Prototypes for these functions are in the header file <TT>`stdio.h'</TT>.
<A NAME="IDX488"></A>
<P>
<A NAME="IDX489"></A>
<U>Function:</U> int <B>printf</B> <I>(const char *<VAR>template</VAR>, ...)</I><P>
The <CODE>printf</CODE> function prints the optional arguments under the
control of the template string <VAR>template</VAR> to the stream
<CODE>stdout</CODE>.  It returns the number of characters printed, or a
negative value if there was an output error.
<P>
<A NAME="IDX490"></A>
<U>Function:</U> int <B>fprintf</B> <I>(FILE *<VAR>stream</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
This function is just like <CODE>printf</CODE>, except that the output is
written to the stream <VAR>stream</VAR> instead of <CODE>stdout</CODE>.
<P>
<A NAME="IDX491"></A>
<U>Function:</U> int <B>sprintf</B> <I>(char *<VAR>s</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
This is like <CODE>printf</CODE>, except that the output is stored in the character
array <VAR>s</VAR> instead of written to a stream.  A null character is written
to mark the end of the string.
<P>
The <CODE>sprintf</CODE> function returns the number of characters stored in
the array <VAR>s</VAR>, not including the terminating null character.
<P>
The behavior of this function is undefined if copying takes place
between objects that overlap--for example, if <VAR>s</VAR> is also given
as an argument to be printed under control of the <SAMP>`%s'</SAMP> conversion.
See section <A HREF="library_5.html#SEC61" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_5.html#SEC61">Copying and Concatenation</A>.
<P>
<STRONG>Warning:</STRONG> The <CODE>sprintf</CODE> function can be <STRONG>dangerous</STRONG>
because it can potentially output more characters than can fit in the
allocation size of the string <VAR>s</VAR>.  Remember that the field width
given in a conversion specification is only a <EM>minimum</EM> value.
<P>
To avoid this problem, you can use <CODE>snprintf</CODE> or <CODE>asprintf</CODE>,
described below.
<P>
<A NAME="IDX492"></A>
<U>Function:</U> int <B>snprintf</B> <I>(char *<VAR>s</VAR>, size_t <VAR>size</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
The <CODE>snprintf</CODE> function is similar to <CODE>sprintf</CODE>, except that
the <VAR>size</VAR> argument specifies the maximum number of characters to
produce.  The trailing null character is counted towards this limit, so
you should allocate at least <VAR>size</VAR> characters for the string <VAR>s</VAR>.
<P>
The return value is the number of characters stored, not including the
terminating null.  If this value equals <VAR>size</VAR>, then there was not
enough space in <VAR>s</VAR> for all the output.  You should try again with a
bigger output string.  Here is an example of doing this:
<P>
<PRE>
/* Construct a message describing the value of a variable
   whose name is <VAR>name</VAR> and whose value is <VAR>value</VAR>. */
char *
make_message (char *name, char *value)
{
  /* Guess we need no more than 100 chars of space. */
  int size = 100;
  char *buffer = (char *) xmalloc (size);
  while (1)
    {
      /* Try to print in the allocated space. */
      int nchars = snprintf (buffer, size,
                             "value of %s is %s", name, value);
      /* If that worked, return the string. */
      if (nchars &#60; size)
        return buffer;
      /* Else try again with twice as much space. */
      size *= 2;
      buffer = (char *) xrealloc (size, buffer);
    }
}
</PRE>
<P>
In practice, it is often easier just to use <CODE>asprintf</CODE>, below.
<P>
<H3><A NAME="SEC136" HREF="library_toc.html#SEC136" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC136">Dynamically Allocating Formatted Output</A></H3>
<P>
The functions in this section do formatted output and place the results
in dynamically allocated memory.
<P>
<A NAME="IDX493"></A>
<U>Function:</U> int <B>asprintf</B> <I>(char **<VAR>ptr</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
This function is similar to <CODE>sprintf</CODE>, except that it dynamically
allocates a string (as with <CODE>malloc</CODE>; see section <A HREF="library_3.html#SEC21" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC21">Unconstrained Allocation</A>) to hold the output, instead of putting the output in a
buffer you allocate in advance.  The <VAR>ptr</VAR> argument should be the
address of a <CODE>char *</CODE> object, and <CODE>asprintf</CODE> stores a pointer
to the newly allocated string at that location.
<P>
Here is how to use <CODE>asprint</CODE> to get the same result as the
<CODE>snprintf</CODE> example, but more easily:
<P>
<PRE>
/* Construct a message describing the value of a variable
   whose name is <VAR>name</VAR> and whose value is <VAR>value</VAR>. */
char *
make_message (char *name, char *value)
{
  char *result;
  asprintf (&#38;result, "value of %s is %s", name, value);
  return result;
}
</PRE>
<P>
<A NAME="IDX494"></A>
<U>Function:</U> int <B>obstack_printf</B> <I>(struct obstack *<VAR>obstack</VAR>, const char *<VAR>template</VAR>, ...)</I><P>
This function is similar to <CODE>asprintf</CODE>, except that it uses the
obstack <VAR>obstack</VAR> to allocate the space.  See section <A HREF="library_3.html#SEC33" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC33">Obstacks</A>.
<P>
The characters are written onto the end of the current object.
To get at them, you must finish the object with <CODE>obstack_finish</CODE>
(see section <A HREF="library_3.html#SEC39" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC39">Growing Objects</A>).<P>
<H3><A NAME="SEC137" HREF="library_toc.html#SEC137" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC137">Variable Arguments Output Functions</A></H3>
<P>
The functions <CODE>vprintf</CODE> and friends are provided so that you can
define your own variadic <CODE>printf</CODE>-like functions that make use of
the same internals as the built-in formatted output functions.
<P>
The most natural way to define such functions would be to use a language
construct to say, "Call <CODE>printf</CODE> 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.
<P>
Since that method is impossible, we provide alternative functions, the
<CODE>vprintf</CODE> series, which lets you pass a <CODE>va_list</CODE> to describe
"all of my arguments after the first five."
<P>
Before calling <CODE>vprintf</CODE> or the other functions listed in this
section, you <EM>must</EM> call <CODE>va_start</CODE> (see section <A HREF="library_28.html#SEC472" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_28.html#SEC472">Variadic Functions</A>) to initialize a pointer to the variable arguments.  Then you
can call <CODE>va_arg</CODE> to fetch the arguments that you want to handle
yourself.  This advances the pointer past those arguments.
<P>
Once your <CODE>va_list</CODE> pointer is pointing at the argument of your
choice, you are ready to call <CODE>vprintf</CODE>.  That argument and all
subsequent arguments that were passed to your function are used by
<CODE>vprintf</CODE> along with the template that you specified separately.
<P>
In some other systems, the <CODE>va_list</CODE> pointer may become invalid
after the call to <CODE>vprintf</CODE>, so you must not use <CODE>va_arg</CODE>
after you call <CODE>vprintf</CODE>.  Instead, you should call <CODE>va_end</CODE>
to retire the pointer from service.  However, you can safely call
<CODE>va_start</CODE> on another pointer variable and begin fetching the
arguments again through that pointer.  Calling <CODE>vfprintf</CODE> does
not destroy the argument list of your function, merely the particular
pointer that you passed to it.
<P>
The GNU library does not have such restrictions.  You can safely continue
to fetch arguments from a <CODE>va_list</CODE> pointer after passing it to
<CODE>vprintf</CODE>, and <CODE>va_end</CODE> is a no-op.
<P>
Prototypes for these functions are declared in <TT>`stdio.h'</TT>.
<A NAME="IDX495"></A>
<P>
<A NAME="IDX496"></A>
<U>Function:</U> int <B>vprintf</B> <I>(const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
This function is similar to <CODE>printf</CODE> except that, instead of taking
a variable number of arguments directly, it takes an argument list
pointer <VAR>ap</VAR>.
<P>
<A NAME="IDX497"></A>
<U>Function:</U> int <B>vfprintf</B> <I>(FILE *<VAR>stream</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
This is the equivalent of <CODE>fprintf</CODE> with the variable argument list
specified directly as for <CODE>vprintf</CODE>.
<P>
<A NAME="IDX498"></A>
<U>Function:</U> int <B>vsprintf</B> <I>(char *<VAR>s</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
This is the equivalent of <CODE>sprintf</CODE> with the variable argument list
specified directly as for <CODE>vprintf</CODE>.
<P>
<A NAME="IDX499"></A>
<U>Function:</U> int <B>vsnprintf</B> <I>(char *<VAR>s</VAR>, size_t <VAR>size</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
This is the equivalent of <CODE>snprintf</CODE> with the variable argument list
specified directly as for <CODE>vprintf</CODE>.
<P>
<A NAME="IDX500"></A>
<U>Function:</U> int <B>vasprintf</B> <I>(char **<VAR>ptr</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
The <CODE>vasprintf</CODE> function is the equivalent of <CODE>asprintf</CODE> with the
variable argument list specified directly as for <CODE>vprintf</CODE>.
<P>
<A NAME="IDX501"></A>
<U>Function:</U> int <B>obstack_vprintf</B> <I>(struct obstack *<VAR>obstack</VAR>, const char *<VAR>template</VAR>, va_list <VAR>ap</VAR>)</I><P>
The <CODE>obstack_vprintf</CODE> function is the equivalent of
<CODE>obstack_printf</CODE> with the variable argument list specified directly
as for <CODE>vprintf</CODE>.<P>
Here's an example showing how you might use <CODE>vfprintf</CODE>.  This is a
function that prints error messages to the stream <CODE>stderr</CODE>, along
with a prefix indicating the name of the program
(see section <A HREF="library_2.html#SEC17" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_2.html#SEC17">Error Messages</A>, for a description of 
<CODE>program_invocation_short_name</CODE>).
<P>
<PRE>
#include &#60;stdio.h&#62;
#include &#60;stdarg.h&#62;

void
eprintf (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);
}
</PRE>
<P>
You could call <CODE>eprintf</CODE> like this:
<P>
<PRE>
eprintf ("file `%s' does not exist\n", filename);
</PRE>
<P>
<A NAME="IDX502"></A>
<H3><A NAME="SEC138" HREF="library_toc.html#SEC138" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC138">Parsing a Template String</A></H3>
<P>
You can use the function <CODE>parse_printf_format</CODE> to obtain
information about the number and types of arguments that are expected by
a given template string.  This func