You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
668 lines
25 KiB
HTML
668 lines
25 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<!-- Created by GNU Texinfo 6.4, http://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<title>sprintf (The Red Hat newlib C Library)</title>
|
|
|
|
<meta name="description" content="sprintf (The Red Hat newlib C Library)">
|
|
<meta name="keywords" content="sprintf (The Red Hat newlib C Library)">
|
|
<meta name="resource-type" content="document">
|
|
<meta name="distribution" content="global">
|
|
<meta name="Generator" content="makeinfo">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<link href="index.html#Top" rel="start" title="Top">
|
|
<link href="Document-Index.html#Document-Index" rel="index" title="Document Index">
|
|
<link href="Document-Index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
|
<link href="Stdio.html#Stdio" rel="up" title="Stdio">
|
|
<link href="sscanf.html#sscanf" rel="next" title="sscanf">
|
|
<link href="siscanf.html#siscanf" rel="prev" title="siscanf">
|
|
<style type="text/css">
|
|
<!--
|
|
a.summary-letter {text-decoration: none}
|
|
blockquote.indentedblock {margin-right: 0em}
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
|
blockquote.smallquotation {font-size: smaller}
|
|
div.display {margin-left: 3.2em}
|
|
div.example {margin-left: 3.2em}
|
|
div.lisp {margin-left: 3.2em}
|
|
div.smalldisplay {margin-left: 3.2em}
|
|
div.smallexample {margin-left: 3.2em}
|
|
div.smalllisp {margin-left: 3.2em}
|
|
kbd {font-style: oblique}
|
|
pre.display {font-family: inherit}
|
|
pre.format {font-family: inherit}
|
|
pre.menu-comment {font-family: serif}
|
|
pre.menu-preformatted {font-family: serif}
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
|
pre.smallexample {font-size: smaller}
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
|
pre.smalllisp {font-size: smaller}
|
|
span.nolinebreak {white-space: nowrap}
|
|
span.roman {font-family: initial; font-weight: normal}
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
|
ul.no-bullet {list-style: none}
|
|
-->
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en">
|
|
<a name="sprintf"></a>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="sscanf.html#sscanf" accesskey="n" rel="next">sscanf</a>, Previous: <a href="siscanf.html#siscanf" accesskey="p" rel="prev">siscanf</a>, Up: <a href="Stdio.html#Stdio" accesskey="u" rel="up">Stdio</a> [<a href="Document-Index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Document-Index.html#Document-Index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<hr>
|
|
<a name="sprintf_002c-fprintf_002c-printf_002c-snprintf_002c-asprintf_002c-asnprintf_002d_002d_002dformat-output"></a>
|
|
<h3 class="section">4.61 <code>sprintf</code>, <code>fprintf</code>, <code>printf</code>, <code>snprintf</code>, <code>asprintf</code>, <code>asnprintf</code>—format output</h3>
|
|
<a name="index-fprintf"></a>
|
|
<a name="index-_005ffprintf_005fr"></a>
|
|
<a name="index-printf"></a>
|
|
<a name="index-_005fprintf_005fr"></a>
|
|
<a name="index-asprintf"></a>
|
|
<a name="index-_005fasprintf_005fr"></a>
|
|
<a name="index-sprintf"></a>
|
|
<a name="index-_005fsprintf_005fr"></a>
|
|
<a name="index-snprintf"></a>
|
|
<a name="index-_005fsnprintf_005fr"></a>
|
|
<a name="index-asnprintf"></a>
|
|
<a name="index-_005fasnprintf_005fr"></a>
|
|
<p><strong>Synopsis</strong>
|
|
</p><div class="example">
|
|
<pre class="example">#include <stdio.h>
|
|
|
|
int printf(const char *restrict <var>format</var>, ...);
|
|
int fprintf(FILE *restrict <var>fd</var>, const char *restrict <var>format</var>, ...);
|
|
int sprintf(char *restrict <var>str</var>, const char *restrict <var>format</var>, ...);
|
|
int snprintf(char *restrict <var>str</var>, size_t <var>size</var>, const char *restrict <var>format</var>,
|
|
...);
|
|
int asprintf(char **restrict <var>strp</var>, const char *restrict <var>format</var>, ...);
|
|
char *asnprintf(char *restrict <var>str</var>, size_t *restrict <var>size</var>, const char *restrict <var>format</var>,
|
|
...);
|
|
|
|
int _printf_r(struct _reent *<var>ptr</var>, const char *restrict <var>format</var>, ...);
|
|
int _fprintf_r(struct _reent *<var>ptr</var>, FILE *restrict <var>fd</var>,
|
|
const char *restrict <var>format</var>, ...);
|
|
int _sprintf_r(struct _reent *<var>ptr</var>, char *restrict <var>str</var>,
|
|
const char *restrict <var>format</var>, ...);
|
|
int _snprintf_r(struct _reent *<var>ptr</var>, char *restrict <var>str</var>, size_t <var>size</var>,
|
|
const char *restrict <var>format</var>, ...);
|
|
int _asprintf_r(struct _reent *<var>ptr</var>, char **restrict <var>strp</var>,
|
|
const char *restrict <var>format</var>, ...);
|
|
char *_asnprintf_r(struct _reent *<var>ptr</var>, char *restrict <var>str</var>,
|
|
size_t *restrict <var>size</var>, const char *restrict <var>format</var>, ...);
|
|
|
|
</pre></div>
|
|
<p><strong>Description</strong><br>
|
|
<code>printf</code> accepts a series of arguments, applies to each a
|
|
format specifier from <code>*<var>format</var></code>, and writes the
|
|
formatted data to <code>stdout</code>, without a terminating NUL
|
|
character. The behavior of <code>printf</code> is undefined if there
|
|
are not enough arguments for the format. <code>printf</code> returns
|
|
when it reaches the end of the format string. If there are
|
|
more arguments than the format requires, excess arguments are
|
|
ignored.
|
|
</p>
|
|
<p><code>fprintf</code> is like <code>printf</code>, except that output is directed
|
|
to the stream <var>fd</var> rather than <code>stdout</code>.
|
|
</p>
|
|
<p><code>sprintf</code> is like <code>printf</code>, except that output is directed
|
|
to the buffer <var>str</var>, and a terminating NUL is output.
|
|
Behavior is undefined if more output is generated than the
|
|
buffer can hold.
|
|
</p>
|
|
<p><code>snprintf</code> is like <code>sprintf</code>, except that output is
|
|
limited to at most <var>size</var> bytes, including the terminating
|
|
<code>NUL</code>. As a special case, if <var>size</var> is 0, <var>str</var> can be
|
|
NULL, and <code>snprintf</code> merely calculates how many bytes would
|
|
be printed.
|
|
</p>
|
|
<p><code>asprintf</code> is like <code>sprintf</code>, except that the output is
|
|
stored in a dynamically allocated buffer, <var>pstr</var>, which
|
|
should be freed later with <code>free</code>.
|
|
</p>
|
|
<p><code>asnprintf</code> is like <code>sprintf</code>, except that the return type
|
|
is either the original <var>str</var> if it was large enough, or a
|
|
dynamically allocated string if the output exceeds *<var>size</var>;
|
|
the length of the result is returned in *<var>size</var>. When
|
|
dynamic allocation occurs, the contents of the original
|
|
<var>str</var> may have been modified.
|
|
</p>
|
|
<p>For <code>sprintf</code>, <code>snprintf</code>, and <code>asnprintf</code>, the behavior
|
|
is undefined if the output <code>*<var>str</var></code> overlaps with one of
|
|
the arguments. Behavior is also undefined if the argument for
|
|
<code>%n</code> within <code>*<var>format</var></code> overlaps another argument.
|
|
</p>
|
|
<p><var>format</var> is a pointer to a character string containing two
|
|
types of objects: ordinary characters (other than <code>%</code>),
|
|
which are copied unchanged to the output, and conversion
|
|
specifications, each of which is introduced by <code>%</code>. (To
|
|
include <code>%</code> in the output, use <code>%%</code> in the format string.)
|
|
A conversion specification has the following form:
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample"> %[<var>pos</var>][<var>flags</var>][<var>width</var>][.<var>prec</var>][<var>size</var>]<var>type</var>
|
|
</pre></div>
|
|
|
|
<p>The fields of the conversion specification have the following
|
|
meanings:
|
|
</p>
|
|
<ul>
|
|
<li> <var>pos</var>
|
|
|
|
<p>Conversions normally consume arguments in the order that they
|
|
are presented. However, it is possible to consume arguments
|
|
out of order, and reuse an argument for more than one
|
|
conversion specification (although the behavior is undefined
|
|
if the same argument is requested with different types), by
|
|
specifying <var>pos</var>, which is a decimal integer followed by
|
|
’$’. The integer must be between 1 and <NL_ARGMAX> from
|
|
limits.h, and if argument <code>%n$</code> is requested, all earlier
|
|
arguments must be requested somewhere within <var>format</var>. If
|
|
positional parameters are used, then all conversion
|
|
specifications except for <code>%%</code> must specify a position.
|
|
This positional parameters method is a POSIX extension to the C
|
|
standard definition for the functions.
|
|
</p>
|
|
</li><li> <var>flags</var>
|
|
|
|
<p><var>flags</var> is an optional sequence of characters which control
|
|
output justification, numeric signs, decimal points, trailing
|
|
zeros, and octal and hex prefixes. The flag characters are
|
|
minus (<code>-</code>), plus (<code>+</code>), space ( ), zero (<code>0</code>), sharp
|
|
(<code>#</code>), and quote (<code>'</code>). They can appear in any
|
|
combination, although not all flags can be used for all
|
|
conversion specification types.
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>'</code></dt>
|
|
<dd><p>A POSIX extension to the C standard. However, this
|
|
implementation presently treats it as a no-op, which
|
|
is the default behavior for the C locale, anyway. (If
|
|
it did what it is supposed to, when <var>type</var> were <code>i</code>,
|
|
<code>d</code>, <code>u</code>, <code>f</code>, <code>F</code>, <code>g</code>, or <code>G</code>, the
|
|
integer portion of the conversion would be formatted
|
|
with thousands’ grouping wide characters.)
|
|
</p>
|
|
</dd>
|
|
<dt><code>-</code></dt>
|
|
<dd><p>The result of the conversion is left
|
|
justified, and the right is padded with
|
|
blanks. If you do not use this flag, the
|
|
result is right justified, and padded on the
|
|
left.
|
|
</p>
|
|
</dd>
|
|
<dt><code>+</code></dt>
|
|
<dd><p>The result of a signed conversion (as
|
|
determined by <var>type</var> of <code>d</code>, <code>i</code>, <code>a</code>,
|
|
<code>A</code>, <code>e</code>, <code>E</code>, <code>f</code>, <code>F</code>, <code>g</code>, or
|
|
<code>G</code>) will always begin with a plus or minus
|
|
sign. (If you do not use this flag, positive
|
|
values do not begin with a plus sign.)
|
|
</p>
|
|
</dd>
|
|
<dt><code>" " (space)</code></dt>
|
|
<dd><p>If the first character of a signed conversion
|
|
specification is not a sign, or if a signed
|
|
conversion results in no characters, the
|
|
result will begin with a space. If the space
|
|
( ) flag and the plus (<code>+</code>) flag both
|
|
appear, the space flag is ignored.
|
|
</p>
|
|
</dd>
|
|
<dt><code>0</code></dt>
|
|
<dd><p>If the <var>type</var> character is <code>d</code>, <code>i</code>,
|
|
<code>o</code>, <code>u</code>, <code>x</code>, <code>X</code>, <code>a</code>, <code>A</code>,
|
|
<code>e</code>, <code>E</code>, <code>f</code>, <code>F</code>, <code>g</code>, or <code>G</code>: leading
|
|
zeros are used to pad the field width
|
|
(following any indication of sign or base); no
|
|
spaces are used for padding. If the zero
|
|
(<code>0</code>) and minus (<code>-</code>) flags both appear,
|
|
the zero (<code>0</code>) flag will be ignored. For
|
|
<code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, and <code>X</code>
|
|
conversions, if a precision <var>prec</var> is
|
|
specified, the zero (<code>0</code>) flag is ignored.
|
|
</p>
|
|
<p>Note that <code>0</code> is interpreted as a flag, not
|
|
as the beginning of a field width.
|
|
</p>
|
|
</dd>
|
|
<dt><code>#</code></dt>
|
|
<dd><p>The result is to be converted to an
|
|
alternative form, according to the <var>type</var>
|
|
character.
|
|
</p></dd>
|
|
</dl>
|
|
|
|
|
|
<p>The alternative form output with the # flag depends on the <var>type</var>
|
|
character:
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>o</code></dt>
|
|
<dd><p>Increases precision to force the first
|
|
digit of the result to be a zero.
|
|
</p>
|
|
</dd>
|
|
<dt><code>x</code></dt>
|
|
<dd><p>A non-zero result will have a <code>0x</code>
|
|
prefix.
|
|
</p>
|
|
</dd>
|
|
<dt><code>X</code></dt>
|
|
<dd><p>A non-zero result will have a <code>0X</code>
|
|
prefix.
|
|
</p>
|
|
</dd>
|
|
<dt><code>a, A, e, E, f, or F</code></dt>
|
|
<dd><p>The result will always contain a
|
|
decimal point even if no digits follow
|
|
the point. (Normally, a decimal point
|
|
appears only if a digit follows it.)
|
|
Trailing zeros are removed.
|
|
</p>
|
|
</dd>
|
|
<dt><code>g or G</code></dt>
|
|
<dd><p>The result will always contain a
|
|
decimal point even if no digits follow
|
|
the point. Trailing zeros are not
|
|
removed.
|
|
</p>
|
|
</dd>
|
|
<dt><code>all others</code></dt>
|
|
<dd><p>Undefined.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
</li><li> <var>width</var>
|
|
|
|
<p><var>width</var> is an optional minimum field width. You can
|
|
either specify it directly as a decimal integer, or
|
|
indirectly by using instead an asterisk (<code>*</code>), in
|
|
which case an <code>int</code> argument is used as the field
|
|
width. If positional arguments are used, then the
|
|
width must also be specified positionally as <code>*m$</code>,
|
|
with m as a decimal integer. Negative field widths
|
|
are treated as specifying the minus (<code>-</code>) flag for
|
|
left justfication, along with a positive field width.
|
|
The resulting format may be wider than the specified
|
|
width.
|
|
</p>
|
|
</li><li> <var>prec</var>
|
|
|
|
<p><var>prec</var> is an optional field; if present, it is
|
|
introduced with ‘<code>.</code>’ (a period). You can specify
|
|
the precision either directly as a decimal integer or
|
|
indirectly by using an asterisk (<code>*</code>), in which case
|
|
an <code>int</code> argument is used as the precision. If
|
|
positional arguments are used, then the precision must
|
|
also be specified positionally as <code>*m$</code>, with m as a
|
|
decimal integer. Supplying a negative precision is
|
|
equivalent to omitting the precision. If only a
|
|
period is specified the precision is zero. The effect
|
|
depends on the conversion <var>type</var>.
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>d, i, o, u, x, or X</code></dt>
|
|
<dd><p>Minimum number of digits to appear. If no
|
|
precision is given, defaults to 1.
|
|
</p>
|
|
</dd>
|
|
<dt><code>a or A</code></dt>
|
|
<dd><p>Number of digits to appear after the decimal
|
|
point. If no precision is given, the
|
|
precision defaults to the minimum needed for
|
|
an exact representation.
|
|
</p>
|
|
</dd>
|
|
<dt><code>e, E, f or F</code></dt>
|
|
<dd><p>Number of digits to appear after the decimal
|
|
point. If no precision is given, the
|
|
precision defaults to 6.
|
|
</p>
|
|
</dd>
|
|
<dt><code>g or G</code></dt>
|
|
<dd><p>Maximum number of significant digits. A
|
|
precision of 0 is treated the same as a
|
|
precision of 1. If no precision is given, the
|
|
precision defaults to 6.
|
|
</p>
|
|
</dd>
|
|
<dt><code>s or S</code></dt>
|
|
<dd><p>Maximum number of characters to print from the
|
|
string. If no precision is given, the entire
|
|
string is printed.
|
|
</p>
|
|
</dd>
|
|
<dt><code>all others</code></dt>
|
|
<dd><p>undefined.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
</li><li> <var>size</var>
|
|
|
|
<p><var>size</var> is an optional modifier that changes the data
|
|
type that the corresponding argument has. Behavior is
|
|
unspecified if a size is given that does not match the
|
|
<var>type</var>.
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>hh</code></dt>
|
|
<dd><p>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or
|
|
<code>X</code>, specifies that the argument should be
|
|
converted to a <code>signed char</code> or <code>unsigned
|
|
char</code> before printing.
|
|
</p>
|
|
<p>With <code>n</code>, specifies that the argument is a
|
|
pointer to a <code>signed char</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>h</code></dt>
|
|
<dd><p>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or
|
|
<code>X</code>, specifies that the argument should be
|
|
converted to a <code>short</code> or <code>unsigned short</code>
|
|
before printing.
|
|
</p>
|
|
<p>With <code>n</code>, specifies that the argument is a
|
|
pointer to a <code>short</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>l</code></dt>
|
|
<dd><p>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or
|
|
<code>X</code>, specifies that the argument is a
|
|
<code>long</code> or <code>unsigned long</code>.
|
|
</p>
|
|
<p>With <code>c</code>, specifies that the argument has
|
|
type <code>wint_t</code>.
|
|
</p>
|
|
<p>With <code>s</code>, specifies that the argument is a
|
|
pointer to <code>wchar_t</code>.
|
|
</p>
|
|
<p>With <code>n</code>, specifies that the argument is a
|
|
pointer to a <code>long</code>.
|
|
</p>
|
|
<p>With <code>a</code>, <code>A</code>, <code>e</code>, <code>E</code>, <code>f</code>, <code>F</code>,
|
|
<code>g</code>, or <code>G</code>, has no effect (because of
|
|
vararg promotion rules, there is no need to
|
|
distinguish between <code>float</code> and <code>double</code>).
|
|
</p>
|
|
</dd>
|
|
<dt><code>ll</code></dt>
|
|
<dd><p>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or
|
|
<code>X</code>, specifies that the argument is a
|
|
<code>long long</code> or <code>unsigned long long</code>.
|
|
</p>
|
|
<p>With <code>n</code>, specifies that the argument is a
|
|
pointer to a <code>long long</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>j</code></dt>
|
|
<dd><p>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or
|
|
<code>X</code>, specifies that the argument is an
|
|
<code>intmax_t</code> or <code>uintmax_t</code>.
|
|
</p>
|
|
<p>With <code>n</code>, specifies that the argument is a
|
|
pointer to an <code>intmax_t</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>z</code></dt>
|
|
<dd><p>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or
|
|
<code>X</code>, specifies that the argument is a <code>size_t</code>.
|
|
</p>
|
|
<p>With <code>n</code>, specifies that the argument is a
|
|
pointer to a <code>size_t</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>t</code></dt>
|
|
<dd><p>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or
|
|
<code>X</code>, specifies that the argument is a
|
|
<code>ptrdiff_t</code>.
|
|
</p>
|
|
<p>With <code>n</code>, specifies that the argument is a
|
|
pointer to a <code>ptrdiff_t</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>L</code></dt>
|
|
<dd><p>With <code>a</code>, <code>A</code>, <code>e</code>, <code>E</code>, <code>f</code>, <code>F</code>,
|
|
<code>g</code>, or <code>G</code>, specifies that the argument
|
|
is a <code>long double</code>.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
</li><li> <var>type</var>
|
|
|
|
<p><var>type</var> specifies what kind of conversion <code>printf</code>
|
|
performs. Here is a table of these:
|
|
</p>
|
|
<dl compact="compact">
|
|
<dt><code>%</code></dt>
|
|
<dd><p>Prints the percent character (<code>%</code>).
|
|
</p>
|
|
</dd>
|
|
<dt><code>c</code></dt>
|
|
<dd><p>Prints <var>arg</var> as single character. If the
|
|
<code>l</code> size specifier is in effect, a multibyte
|
|
character is printed.
|
|
</p>
|
|
</dd>
|
|
<dt><code>C</code></dt>
|
|
<dd><p>Short for <code>%lc</code>. A POSIX extension to the C standard.
|
|
</p>
|
|
</dd>
|
|
<dt><code>s</code></dt>
|
|
<dd><p>Prints the elements of a pointer to <code>char</code>
|
|
until the precision or a null character is
|
|
reached. If the <code>l</code> size specifier is in
|
|
effect, the pointer is to an array of
|
|
<code>wchar_t</code>, and the string is converted to
|
|
multibyte characters before printing.
|
|
</p>
|
|
</dd>
|
|
<dt><code>S</code></dt>
|
|
<dd><p>Short for <code>%ls</code>. A POSIX extension to the C standard.
|
|
</p>
|
|
</dd>
|
|
<dt><code>d or i</code></dt>
|
|
<dd><p>Prints a signed decimal integer; takes an
|
|
<code>int</code>. Leading zeros are inserted as
|
|
necessary to reach the precision. A value of 0 with
|
|
a precision of 0 produces an empty string.
|
|
</p>
|
|
</dd>
|
|
<dt><code>D</code></dt>
|
|
<dd><p>Newlib extension, short for <code>%ld</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>o</code></dt>
|
|
<dd><p>Prints an unsigned octal integer; takes an
|
|
<code>unsigned</code>. Leading zeros are inserted as
|
|
necessary to reach the precision. A value of 0 with
|
|
a precision of 0 produces an empty string.
|
|
</p>
|
|
</dd>
|
|
<dt><code>O</code></dt>
|
|
<dd><p>Newlib extension, short for <code>%lo</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>u</code></dt>
|
|
<dd><p>Prints an unsigned decimal integer; takes an
|
|
<code>unsigned</code>. Leading zeros are inserted as
|
|
necessary to reach the precision. A value of 0 with
|
|
a precision of 0 produces an empty string.
|
|
</p>
|
|
</dd>
|
|
<dt><code>U</code></dt>
|
|
<dd><p>Newlib extension, short for <code>%lu</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>x</code></dt>
|
|
<dd><p>Prints an unsigned hexadecimal integer (using
|
|
<code>abcdef</code> as digits beyond <code>9</code>); takes an
|
|
<code>unsigned</code>. Leading zeros are inserted as
|
|
necessary to reach the precision. A value of 0 with
|
|
a precision of 0 produces an empty string.
|
|
</p>
|
|
</dd>
|
|
<dt><code>X</code></dt>
|
|
<dd><p>Like <code>x</code>, but uses <code>ABCDEF</code> as digits
|
|
beyond <code>9</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>f</code></dt>
|
|
<dd><p>Prints a signed value of the form
|
|
<code>[-]9999.9999</code>, with the precision
|
|
determining how many digits follow the decimal
|
|
point; takes a <code>double</code> (remember that
|
|
<code>float</code> promotes to <code>double</code> as a vararg).
|
|
The low order digit is rounded to even. If
|
|
the precision results in at most DECIMAL_DIG
|
|
digits, the result is rounded correctly; if
|
|
more than DECIMAL_DIG digits are printed, the
|
|
result is only guaranteed to round back to the
|
|
original value.
|
|
</p>
|
|
<p>If the value is infinite, the result is
|
|
<code>inf</code>, and no zero padding is performed. If
|
|
the value is not a number, the result is
|
|
<code>nan</code>, and no zero padding is performed.
|
|
</p>
|
|
</dd>
|
|
<dt><code>F</code></dt>
|
|
<dd><p>Like <code>f</code>, but uses <code>INF</code> and <code>NAN</code> for
|
|
non-finite numbers.
|
|
</p>
|
|
</dd>
|
|
<dt><code>e</code></dt>
|
|
<dd><p>Prints a signed value of the form
|
|
<code>[-]9.9999e[+|-]999</code>; takes a <code>double</code>.
|
|
The digit before the decimal point is non-zero
|
|
if the value is non-zero. The precision
|
|
determines how many digits appear between
|
|
<code>.</code> and <code>e</code>, and the exponent always
|
|
contains at least two digits. The value zero
|
|
has an exponent of zero. If the value is not
|
|
finite, it is printed like <code>f</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>E</code></dt>
|
|
<dd><p>Like <code>e</code>, but using <code>E</code> to introduce the
|
|
exponent, and like <code>F</code> for non-finite
|
|
values.
|
|
</p>
|
|
</dd>
|
|
<dt><code>g</code></dt>
|
|
<dd><p>Prints a signed value in either <code>f</code> or <code>e</code>
|
|
form, based on the given value and
|
|
precision—an exponent less than -4 or
|
|
greater than the precision selects the <code>e</code>
|
|
form. Trailing zeros and the decimal point
|
|
are printed only if necessary; takes a
|
|
<code>double</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>G</code></dt>
|
|
<dd><p>Like <code>g</code>, except use <code>F</code> or <code>E</code> form.
|
|
</p>
|
|
</dd>
|
|
<dt><code>a</code></dt>
|
|
<dd><p>Prints a signed value of the form
|
|
<code>[-]0x1.ffffp[+|-]9</code>; takes a <code>double</code>.
|
|
The letters <code>abcdef</code> are used for digits
|
|
beyond <code>9</code>. The precision determines how
|
|
many digits appear after the decimal point.
|
|
The exponent contains at least one digit, and
|
|
is a decimal value representing the power of
|
|
2; a value of 0 has an exponent of 0.
|
|
Non-finite values are printed like <code>f</code>.
|
|
</p>
|
|
</dd>
|
|
<dt><code>A</code></dt>
|
|
<dd><p>Like <code>a</code>, except uses <code>X</code>, <code>P</code>, and
|
|
<code>ABCDEF</code> instead of lower case.
|
|
</p>
|
|
</dd>
|
|
<dt><code>n</code></dt>
|
|
<dd><p>Takes a pointer to <code>int</code>, and stores a count
|
|
of the number of bytes written so far. No
|
|
output is created.
|
|
</p>
|
|
</dd>
|
|
<dt><code>p</code></dt>
|
|
<dd><p>Takes a pointer to <code>void</code>, and prints it in
|
|
an implementation-defined format. This
|
|
implementation is similar to <code>%#tx</code>), except
|
|
that <code>0x</code> appears even for the NULL pointer.
|
|
</p>
|
|
</dd>
|
|
<dt><code>m</code></dt>
|
|
<dd><p>Prints the output of <code>strerror(errno)</code>; no
|
|
argument is required. A GNU extension.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
</li></ul>
|
|
|
|
|
|
<p><code>_printf_r</code>, <code>_fprintf_r</code>, <code>_asprintf_r</code>,
|
|
<code>_sprintf_r</code>, <code>_snprintf_r</code>, <code>_asnprintf_r</code> are simply
|
|
reentrant versions of the functions above.
|
|
</p>
|
|
<br>
|
|
<p><strong>Returns</strong><br>
|
|
On success, <code>sprintf</code> and <code>asprintf</code> return the number of bytes in
|
|
the output string, except the concluding <code>NUL</code> is not counted.
|
|
<code>snprintf</code> returns the number of bytes that would be in the output
|
|
string, except the concluding <code>NUL</code> is not counted. <code>printf</code> and
|
|
<code>fprintf</code> return the number of characters transmitted.
|
|
<code>asnprintf</code> returns the original <var>str</var> if there was enough room,
|
|
otherwise it returns an allocated string.
|
|
</p>
|
|
<p>If an error occurs, the result of <code>printf</code>, <code>fprintf</code>,
|
|
<code>snprintf</code>, and <code>asprintf</code> is a negative value, and the result of
|
|
<code>asnprintf</code> is NULL. No error returns occur for <code>sprintf</code>. For
|
|
<code>printf</code> and <code>fprintf</code>, <code>errno</code> may be set according to
|
|
<code>fputc</code>. For <code>asprintf</code> and <code>asnprintf</code>, <code>errno</code> may be set
|
|
to ENOMEM if allocation fails, and for <code>snprintf</code>, <code>errno</code> may be
|
|
set to EOVERFLOW if <var>size</var> or the output length exceeds INT_MAX.
|
|
</p>
|
|
<br>
|
|
<p><strong>Bugs</strong><br>
|
|
The “”’ (quote) flag does not work when locale’s thousands_sep is not empty.
|
|
</p>
|
|
<br>
|
|
<p><strong>Portability</strong><br>
|
|
ANSI C requires <code>printf</code>, <code>fprintf</code>, <code>sprintf</code>, and
|
|
<code>snprintf</code>. <code>asprintf</code> and <code>asnprintf</code> are newlib extensions.
|
|
</p>
|
|
<p>The ANSI C standard specifies that implementations must support at
|
|
least formatted output of up to 509 characters. This implementation
|
|
has no inherent limit.
|
|
</p>
|
|
<p>Depending on how newlib was configured, not all format specifiers are
|
|
supported.
|
|
</p>
|
|
<p>Supporting OS subroutines required: <code>close</code>, <code>fstat</code>, <code>isatty</code>,
|
|
<code>lseek</code>, <code>read</code>, <code>sbrk</code>, <code>write</code>.
|
|
</p>
|
|
<br>
|
|
|
|
<hr>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="sscanf.html#sscanf" accesskey="n" rel="next">sscanf</a>, Previous: <a href="siscanf.html#siscanf" accesskey="p" rel="prev">siscanf</a>, Up: <a href="Stdio.html#Stdio" accesskey="u" rel="up">Stdio</a> [<a href="Document-Index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Document-Index.html#Document-Index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|