summaryrefslogtreecommitdiff
path: root/reference/C/MAN/sprintf.htm
blob: c029466b9ee930f75d03996773a6534fb1362597 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
<TITLE>sprintf</TITLE>
<body bgcolor="#ffffcc">
<hr>
<pre>



<h3>SPRINTF(3)           Linux Programmer's Manual           SPRINTF(3)
</h3>

<h3>NAME
</h3>       printf,  fprintf,  sprintf,  vprintf, vfprintf, vsprintf -
       formatted output conversion

<h3>SYNOPSIS
</h3>       #include &lt;stdio.h&gt;

       int printf( const char *format, ...);
       int fprintf( FILE *stream, const char *format, ...);
       int sprintf( char *str, const char *format, ...);

       #include &lt;stdarg.h&gt;

       int vprintf( const char *format, va_list ap);
       int vfprintf( FILE *stream, const  char  *format,  va_list
       ap);
       int vsprintf( char *str, char *format, va_list ap);

<h3>DESCRIPTION
</h3>       The  printf  family of functions produces output according
       to a format as described below.  Printf and vprintf  write
       output  to stdout, the standard output stream; fprintf and
       vfprintf write output to the given output stream; sprintf,
       and  vsprintf  write  to  the character string str.  These
       functions write the output under the control of  a  format
       string  that  specifies how subsequent arguments (or argu-
       ments accessed via the variable-length argument facilities
       of  stdarg(3)  are  converted for output.  These functions
       return the number of characters printed (not including the
       trailing `\0' used to end output to strings).

       The  format string is composed of zero or more directives:
       ordinary characters (not %), which are copied unchanged to
       the  output stream; and conversion specifications, each of
       which results in fetching zero or  more  subsequent  argu-
       ments.  Each conversion specification is introduced by the
       character  %.   The  arguments  must  correspond  properly
       (after  type  promotion)  with  the  conversion specifier.
       After the %, the following appear in sequence:

       o      Zero or more of the following flags:

              #      specifying that the  value  should  be  con-
                     verted  to an ``alternate form''.  For c, d,
                     i, n, p, s, and u conversions,  this  option
                     has  no effect.  For o conversions, the pre-
                     cision of the number is increased  to  force
                     the  first character of the output string to
                     a zero (except if a zero  value  is  printed
                     with  an explicit precision of zero).  For x
                     and X conversions, a non-zero result has the
                     string  `0x'  (or  `0X'  for  X conversions)
                     prepended to it.  For e, E, f, g, and G con-
                     versions,  the  result will always contain a



<h3>BSD MANPAGE              29 November 1993                       1
</h3>




<h3>SPRINTF(3)           Linux Programmer's Manual           SPRINTF(3)
</h3>

                     decimal point, even if no digits  follow  it
                     (normally,  a  decimal  point appears in the
                     results of those conversions only if a digit
                     follows).  For g and G conversions, trailing
                     zeros are not removed  from  the  result  as
                     they would otherwise be.

              0      specifying  zero  padding.   For all conver-
                     sions  except  n,  the  converted  value  is
                     padded  on  the  left with zeros rather than
                     blanks.  If a  precision  is  given  with  a
                     numeric  conversion  (d,  i, o, u, i, x, and
                     X), the 0 flag is ignored.

              -      (a negative field width flag) indicates  the
                     converted  value  is  to be left adjusted on
                     the field boundary.  Except  for  n  conver-
                     sions,  the converted value is padded on the
                     right with blanks, rather than on  the  left
                     with  blanks or zeros.  A - overrides a 0 if
                     both are given.

                     (a space) specifying that a blank should  be
                     left  before a positive number produced by a
                     signed conversion (d, e, E, f, g, G, or  i).

              +      specifying  that  a  sign  always  be placed
                     before a number produced by a signed conver-
                     sion.   A  +  overrides  a space if both are
                     used.

       o      An optional decimal digit string specifying a mini-
              mum  field width.  If the converted value has fewer
              characters than the field width, it will be  padded
              with  spaces  on  the  left (or right, if the left-
              adjustment flag has been given)  to  fill  out  the
              field width.

       o      An  optional  precision,  in  the  form of a period
              (`.')  followed by an optional  digit  string.   If
              the digit string is omitted, the precision is taken
              as zero.  This gives the minimum number  of  digits
              to appear for d, i, o, u, x, and X conversions, the
              number of digits to appear after the  decimal-point
              for  e, E, and f conversions, the maximum number of
              significant digits for g and G conversions, or  the
              maximum  number  of characters to be printed from a
              string for s conversions.

       o      The optional character h, specifying that a follow-
              ing d, i, o, u, x, or X conversion corresponds to a
              short int or unsigned short int argument, or that a
              following  n conversion corresponds to a pointer to
              a short int argument.



<h3>BSD MANPAGE              29 November 1993                       2
</h3>




<h3>SPRINTF(3)           Linux Programmer's Manual           SPRINTF(3)
</h3>

       o      The optional character l (ell)  specifying  that  a
              following d, i, o, u, x, or X conversion applies to
              a pointer to a long int or unsigned long int  argu-
              ment,  or that a following n conversion corresponds
              to a pointer to a long int argument.

       o      The character L specifying that a following  e,  E,
              f,  g, or G conversion corresponds to a long double
              argument.

       o      A character that specifies the type  of  conversion
              to be applied.

       A  field  width or precision, or both, may be indicated by
       an asterisk `*' instead of a digit string.  In this  case,
       an  int argument supplies the field width or precision.  A
       negative field width is treated as a left adjustment  flag
       followed  by  a positive field width; a negative precision
       is treated as though it were missing.

       The conversion specifiers and their meanings are:

       diouxX The int (or appropriate variant) argument  is  con-
              verted  to signed decimal (d and i), unsigned octal
              (o, unsigned decimal (u, or unsigned hexadecimal (x
              and X) notation.  The letters abcdef are used for x
              conversions; the letters ABCDEF are used for X con-
              versions.  The precision, if any, gives the minimum
              number of digits that must appear; if the converted
              value  requires  fewer  digits, it is padded on the
              left with zeros.

       DOU    The long int argument is converted to signed  deci-
              mal, unsigned octal, or unsigned decimal, as if the
              format had been ld, lo, or lu respectively.   These
              conversion  characters  are  deprecated,  and  will
              eventually disappear.

       eE     The double argument is rounded and converted in the
              style  [-]d.dddedd  where there is one digit before
              the decimal-point character and the number of  dig-
              its after it is equal to the precision; if the pre-
              cision is missing, it is taken as 6; if the  preci-
              sion  is  zero, no decimal-point character appears.
              An E conversion uses the letter E (rather  than  e)
              to  introduce  the  exponent.   The exponent always
              contains at least two digits; if the value is zero,
              the exponent is 00.

       f      The  double  argument  is  rounded and converted to
              decimal notation in the style [-]ddd.ddd, where the
              number  of digits after the decimal-point character
              is equal to the precision  specification.   If  the
              precision  is  missing,  it  is  taken as 6; if the



<h3>BSD MANPAGE              29 November 1993                       3
</h3>




<h3>SPRINTF(3)           Linux Programmer's Manual           SPRINTF(3)
</h3>

              precision  is  explicitly  zero,  no  decimal-point
              character  appears.  If a decimal point appears, at
              least one digit appears before it.

       g      The double argument is converted in style  f  or  e
              (or  E for G conversions).  The precision specifies
              the number of significant digits.  If the precision
              is missing, 6 digits are given; if the precision is
              zero, it is treated as 1.  Style e is used  if  the
              exponent  from  its  conversion  is less than -4 or
              greater than or equal to the  precision.   Trailing
              zeros  are  removed from the fractional part of the
              result; a decimal point appears only if it is  fol-
              lowed by at least one digit.

       c      The  int argument is converted to an unsigned char,
              and the resulting character is written.

       s      The ``char *'' argument is expected to be a pointer
              to  an  array  of  character  type  (pointer  to  a
              string).  Characters from the array are written  up
              to (but not including) a terminating NUL character;
              if a precision is specified, no more than the  num-
              ber  specified  are  written.   If  a  precision is
              given, no null character need be  present;  if  the
              precision  is not specified, or is greater than the
              size of the array, the array must contain a  termi-
              nating NUL character.

       p      The  ``void *'' pointer argument is printed in hex-
              adecimal (as if by %#x or %#lx).

       n      The number of characters written so far  is  stored
              into  the  integer  indicated  by the ``int *'' (or
              variant) pointer argument.   No  argument  is  con-
              verted.

       %      A  `%'  is  written.  No argument is converted. The
              complete conversion specification is `%%'.

       In no case does a non-existent or small field width  cause
       truncation  of  a  field; if the result of a conversion is
       wider than the field width, the field is expanded to  con-
       tain the conversion result.


<h3>EXAMPLES
</h3>       To  print  a  date  and  time in the form `Sunday, July 3,
       10:02', where weekday and month are pointers to strings:
              #include &lt;stdio.h&gt;
              fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
                   weekday, month, day, hour, min);

       To print to five decimal places:



<h3>BSD MANPAGE              29 November 1993                       4
</h3>




<h3>SPRINTF(3)           Linux Programmer's Manual           SPRINTF(3)
</h3>

              #include &lt;math.h&gt;
              #include &lt;stdio.h&gt;
              fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

       To allocate a 128 byte string and print into it:
              #include &lt;stdio.h&gt;
              #include &lt;stdlib.h&gt;
              #include &lt;stdarg.h&gt;
              char *newfmt(const char *fmt, ...)
              {
                        char *p;
                        va_list ap;
                        if ((p = malloc(128)) == NULL)
                             return (NULL);
                        va_start(ap, fmt);
                        (void) vsnprintf(p, 128, fmt, ap);
                        va_end(ap);
                        return (p);
              }

</pre>
<hr>
<h3>SEE ALSO
</h3><p>
<a href=printf.htm>printf</a>, 
<a href=scanf.htm>scanf</a>, 
<pre>

<h3>STANDARDS
</h3>       The  fprintf,  printf,  sprintf,  vprintf,  vfprintf,  and
       vsprintf  functions  conform  to  ANSI C3.159-1989 (``ANSI
       C'').

<h3>BUGS
</h3>       Some floating point conversions under Linux  cause  memory
       leaks.

       The conversion formats %D, %O, and %U are not standard and
       are provided only for backward compatibility.   These  may
       not be provided under Linux.

       The  effect of padding the %p format with zeros (either by
       the 0 flag or by specifying a precision), and  the  benign
       effect  (i.e.,  none)  of  the # flag on %n and %p conver-
       sions, as well as other nonsensical combinations  such  as
       %Ld,   are  not  standard;  such  combinations  should  be
       avoided.

       Because sprintf and vsprintf  assume  an  infinitely  long
       string, callers must be careful not to overflow the actual
       space; this is often impossible to assure.











<h3>BSD MANPAGE              29 November 1993                       5
</h3>


</pre>
<P>
<hr>
<p>
<center>
<table border=2 width=80%>
<tr align=center>
<td width=25%>
<a href=../cref.html>Top</a>
</td><td width=25%>
<a href=../master_index.html>Master Index</a>
</td><td width=25%>
<a href=../SYNTAX/keywords.html>Keywords</a>
</td><td width=25%>
<a href=../FUNCTIONS/funcref.htm>Functions</a>
</td>
</tr>
</table>
</center>
<p>
<hr>

This manual page was brought to you by <i>mjl_man V-2.0</i>