| <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: <a rel="next" accesskey="n" href="Dynamic-Output.html#Dynamic-Output">Dynamic Output</a>, |
| Previous: <a rel="previous" accesskey="p" href="Other-Output-Conversions.html#Other-Output-Conversions">Other Output Conversions</a>, |
| Up: <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"> |
| — 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"> |
| — 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"> |
| — 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"> |
| — 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"> |
| — 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—for example, if <var>s</var> is also given |
| as an argument to be printed under control of the ‘<samp><span class="samp">%s</span></samp>’ 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"> |
| — 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 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"> |
| — 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 >= 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 C99<!-- /@w --> standard. |
| </p></blockquote></div> |
| |
| </body></html> |
| |
