<html lang="en">
<head>
<title>Formatted Output Functions - The GNU C Library</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="The GNU C Library">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Formatted-Output.html#Formatted-Output" title="Formatted Output">
<link rel="prev" href="Other-Output-Conversions.html#Other-Output-Conversions" title="Other Output Conversions">
<link rel="next" href="Dynamic-Output.html#Dynamic-Output" title="Dynamic Output">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU C library.

This is Edition 0.12, last updated 2007-10-27,
of `The GNU C Library Reference Manual', for version
2.8 (Sourcery G++ Lite 2011.03-41).

Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.  Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Formatted-Output-Functions"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Dynamic-Output.html#Dynamic-Output">Dynamic Output</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Other-Output-Conversions.html#Other-Output-Conversions">Other Output Conversions</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Formatted-Output.html#Formatted-Output">Formatted Output</a>
<hr>
</div>

<h4 class="subsection">12.12.7 Formatted Output Functions</h4>

<p>This section describes how to call <code>printf</code> and related functions. 
Prototypes for these functions are in the header file <samp><span class="file">stdio.h</span></samp>. 
Because these functions take a variable number of arguments, you
<em>must</em> declare prototypes for them before using them.  Of course,
the easiest way to make sure you have all the right prototypes is to
just include <samp><span class="file">stdio.h</span></samp>. 
<a name="index-stdio_002eh-1026"></a>
<!-- stdio.h -->
<!-- ISO -->

<div class="defun">
&mdash; Function: int <b>printf</b> (<var>const char *template, <small class="dots">...</small></var>)<var><a name="index-printf-1027"></a></var><br>
<blockquote><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></blockquote></div>

<!-- wchar.h -->
<!-- ISO -->
<div class="defun">
&mdash; Function: int <b>wprintf</b> (<var>const wchar_t *template, <small class="dots">...</small></var>)<var><a name="index-wprintf-1028"></a></var><br>
<blockquote><p>The <code>wprintf</code> function prints the optional arguments under the
control of the wide template string <var>template</var> to the stream
<code>stdout</code>.  It returns the number of wide characters printed, or a
negative value if there was an output error. 
</p></blockquote></div>

<!-- stdio.h -->
<!-- ISO -->
<div class="defun">
&mdash; Function: int <b>fprintf</b> (<var>FILE *stream, const char *template, <small class="dots">...</small></var>)<var><a name="index-fprintf-1029"></a></var><br>
<blockquote><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></blockquote></div>

<!-- wchar.h -->
<!-- ISO -->
<div class="defun">
&mdash; Function: int <b>fwprintf</b> (<var>FILE *stream, const wchar_t *template, <small class="dots">...</small></var>)<var><a name="index-fwprintf-1030"></a></var><br>
<blockquote><p>This function is just like <code>wprintf</code>, except that the output is
written to the stream <var>stream</var> instead of <code>stdout</code>. 
</p></blockquote></div>

<!-- stdio.h -->
<!-- ISO -->
<div class="defun">
&mdash; Function: int <b>sprintf</b> (<var>char *s, const char *template, <small class="dots">...</small></var>)<var><a name="index-sprintf-1031"></a></var><br>
<blockquote><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&mdash;for example, if <var>s</var> is also given
as an argument to be printed under control of the &lsquo;<samp><span class="samp">%s</span></samp>&rsquo; conversion. 
See <a href="Copying-and-Concatenation.html#Copying-and-Concatenation">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></blockquote></div>

<!-- wchar.h -->
<!-- GNU -->
<div class="defun">
&mdash; Function: int <b>swprintf</b> (<var>wchar_t *s, size_t size, const wchar_t *template, <small class="dots">...</small></var>)<var><a name="index-swprintf-1032"></a></var><br>
<blockquote><p>This is like <code>wprintf</code>, except that the output is stored in the
wide character array <var>ws</var> instead of written to a stream.  A null
wide character is written to mark the end of the string.  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> wide characters for the string <var>ws</var>.

        <p>The return value is the number of characters generated for the given
input, excluding the trailing null.  If not all output fits into the
provided buffer a negative value is returned.  You should try again with
a bigger output string.  <em>Note:</em> this is different from how
<code>snprintf</code> handles this situation.

        <p>Note that the corresponding narrow stream function takes fewer
parameters.  <code>swprintf</code> in fact corresponds to the <code>snprintf</code>
function.  Since the <code>sprintf</code> function can be dangerous and should
be avoided the ISO&nbsp;C<!-- /@w --> committee refused to make the same mistake
again and decided to not define an function exactly corresponding to
<code>sprintf</code>. 
</p></blockquote></div>

<!-- stdio.h -->
<!-- GNU -->
<div class="defun">
&mdash; Function: int <b>snprintf</b> (<var>char *s, size_t size, const char *template, <small class="dots">...</small></var>)<var><a name="index-snprintf-1033"></a></var><br>
<blockquote><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 which would be generated
for the given input, excluding the trailing null.  If this value is
greater or equal to <var>size</var>, not all characters from the result have
been stored in <var>s</var>.  You should try again with a bigger output
string.  Here is an example of doing this:

     <pre class="smallexample">          /* <span class="roman">Construct a message describing the value of a variable</span>
             <span class="roman">whose name is </span><var>name</var><span class="roman"> and whose value is </span><var>value</var><span class="roman">.</span> */
          char *
          make_message (char *name, char *value)
          {
            /* <span class="roman">Guess we need no more than 100 chars of space.</span> */
            int size = 100;
            char *buffer = (char *) xmalloc (size);
            int nchars;
            if (buffer == NULL)
              return NULL;
          
           /* <span class="roman">Try to print in the allocated space.</span> */
            nchars = snprintf (buffer, size, "value of %s is %s",
                               name, value);
            if (nchars &gt;= size)
              {
                /* <span class="roman">Reallocate buffer now that we know
                   how much space is needed.</span> */
                size = nchars + 1;
                buffer = (char *) xrealloc (buffer, size);
          
                if (buffer != NULL)
                  /* <span class="roman">Try again.</span> */
                  snprintf (buffer, size, "value of %s is %s",
                            name, value);
              }
            /* <span class="roman">The last call worked, return the string.</span> */
            return buffer;
          }
</pre>
        <p>In practice, it is often easier just to use <code>asprintf</code>, below.

        <p><strong>Attention:</strong> In versions of the GNU C library prior to 2.1 the
return value is the number of characters stored, not including the
terminating null; unless there was not enough space in <var>s</var> to
store the result in which case <code>-1</code> is returned.  This was
changed in order to comply with the ISO&nbsp;C99<!-- /@w --> standard. 
</p></blockquote></div>

   </body></html>