]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1999 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
2e2d817c MK |
3 | .\" Earlier versions of this page influenced the present text. |
4 | .\" It was derived from a Berkeley page with version | |
5 | .\" @(#)printf.3 6.14 (Berkeley) 7/30/91 | |
6 | .\" converted for Linux by faith@cs.unc.edu, updated by | |
7 | .\" Helmut.Geyer@iwr.uni-heidelberg.de, agulbra@troll.no and Bruno Haible. | |
8 | .\" | |
1dd72f9c | 9 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
10 | .\" This is free documentation; you can redistribute it and/or |
11 | .\" modify it under the terms of the GNU General Public License as | |
12 | .\" published by the Free Software Foundation; either version 2 of | |
13 | .\" the License, or (at your option) any later version. | |
14 | .\" | |
15 | .\" The GNU General Public License's references to "object code" | |
16 | .\" and "executables" are to be interpreted as the output of any | |
17 | .\" document formatting or typesetting system, including | |
18 | .\" intermediate and printed output. | |
19 | .\" | |
20 | .\" This manual is distributed in the hope that it will be useful, | |
21 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
22 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
23 | .\" GNU General Public License for more details. | |
24 | .\" | |
25 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
26 | .\" License along with this manual; if not, see |
27 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 28 | .\" %%%LICENSE_END |
fea681da | 29 | .\" |
fea681da MK |
30 | .\" 1999-11-25 aeb - Rewritten, using SUSv2 and C99. |
31 | .\" 2000-07-26 jsm28@hermes.cam.ac.uk - three small fixes | |
32 | .\" 2000-10-16 jsm28@hermes.cam.ac.uk - more fixes | |
33 | .\" | |
35deeb87 | 34 | .TH PRINTF 3 2016-12-12 "GNU" "Linux Programmer's Manual" |
fea681da | 35 | .SH NAME |
5ffdc2fd | 36 | printf, fprintf, dprintf, sprintf, snprintf, vprintf, vfprintf, vdprintf, |
62730046 | 37 | vsprintf, vsnprintf \- formatted output conversion |
fea681da MK |
38 | .SH SYNOPSIS |
39 | .B #include <stdio.h> | |
68e4db0a | 40 | .PP |
fea681da MK |
41 | .BI "int printf(const char *" format ", ...);" |
42 | .br | |
43 | .BI "int fprintf(FILE *" stream ", const char *" format ", ...);" | |
44 | .br | |
62730046 MK |
45 | .BI "int dprintf(int " fd ", const char *" format ", ...);" |
46 | .br | |
fea681da MK |
47 | .BI "int sprintf(char *" str ", const char *" format ", ...);" |
48 | .br | |
49 | .BI "int snprintf(char *" str ", size_t " size ", const char *" format ", ...);" | |
f90f031e | 50 | |
fea681da | 51 | .B #include <stdarg.h> |
68e4db0a | 52 | .PP |
fea681da MK |
53 | .BI "int vprintf(const char *" format ", va_list " ap ); |
54 | .br | |
55 | .BI "int vfprintf(FILE *" stream ", const char *" format ", va_list " ap ); | |
56 | .br | |
62730046 MK |
57 | .BI "int vdprintf(int " fd ", const char *" format ", va_list " ap ); |
58 | .br | |
fea681da MK |
59 | .BI "int vsprintf(char *" str ", const char *" format ", va_list " ap ); |
60 | .br | |
3d54a910 MK |
61 | .BI "int vsnprintf(char *" str ", size_t " size ", const char *" format \ |
62 | ", va_list " ap ); | |
68e4db0a | 63 | .PP |
cc4615cc MK |
64 | .in -4n |
65 | Feature Test Macro Requirements for glibc (see | |
66 | .BR feature_test_macros (7)): | |
67 | .in | |
68e4db0a | 68 | .PP |
cc4615cc MK |
69 | .ad l |
70 | .BR snprintf (), | |
71 | .BR vsnprintf (): | |
a1d525f2 | 72 | .RS 4 |
d59161f9 MK |
73 | _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE || |
74 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE | |
a1d525f2 | 75 | .RE |
68e4db0a | 76 | .PP |
62730046 MK |
77 | .BR dprintf (), |
78 | .BR vdprintf (): | |
79 | .PD 0 | |
80 | .RS 4 | |
81 | .TP 4 | |
82 | Since glibc 2.10: | |
b0da7b8b | 83 | _POSIX_C_SOURCE\ >=\ 200809L |
62730046 MK |
84 | .TP |
85 | Before glibc 2.10: | |
86 | _GNU_SOURCE | |
87 | .RE | |
a1d525f2 | 88 | .ad |
62730046 | 89 | .PD |
fea681da MK |
90 | .SH DESCRIPTION |
91 | The functions in the | |
e511ffb6 | 92 | .BR printf () |
fea681da MK |
93 | family produce output according to a |
94 | .I format | |
c13182ef MK |
95 | as described below. |
96 | The functions | |
e511ffb6 | 97 | .BR printf () |
fea681da | 98 | and |
e511ffb6 | 99 | .BR vprintf () |
fea681da MK |
100 | write output to |
101 | .IR stdout , | |
102 | the standard output stream; | |
e511ffb6 | 103 | .BR fprintf () |
fea681da | 104 | and |
e511ffb6 | 105 | .BR vfprintf () |
fea681da MK |
106 | write output to the given output |
107 | .IR stream ; | |
e511ffb6 | 108 | .BR sprintf (), |
c13182ef | 109 | .BR snprintf (), |
e511ffb6 | 110 | .BR vsprintf () |
fea681da | 111 | and |
e511ffb6 | 112 | .BR vsnprintf () |
fea681da | 113 | write to the character string |
3cf81850 | 114 | .IR str . |
847e0d88 | 115 | .PP |
62730046 MK |
116 | The function |
117 | .BR dprintf () | |
118 | is the same as | |
22b1b752 | 119 | .BR fprintf () |
62730046 MK |
120 | except that it outputs to a file descriptor, |
121 | .IR fd , | |
122 | instead of to a | |
123 | .I stdio | |
124 | stream. | |
847e0d88 | 125 | .PP |
fea681da | 126 | The functions |
11050e19 MK |
127 | .BR snprintf () |
128 | and | |
129 | .BR vsnprintf () | |
130 | write at most | |
131 | .I size | |
31a6818e | 132 | bytes (including the terminating null byte (\(aq\e0\(aq)) to |
11050e19 | 133 | .IR str . |
847e0d88 | 134 | .PP |
11050e19 | 135 | The functions |
e511ffb6 MK |
136 | .BR vprintf (), |
137 | .BR vfprintf (), | |
62730046 | 138 | .BR vdprintf (), |
e511ffb6 MK |
139 | .BR vsprintf (), |
140 | .BR vsnprintf () | |
fea681da | 141 | are equivalent to the functions |
e511ffb6 MK |
142 | .BR printf (), |
143 | .BR fprintf (), | |
62730046 | 144 | .BR dprintf (), |
e511ffb6 MK |
145 | .BR sprintf (), |
146 | .BR snprintf (), | |
f6b55d82 MK |
147 | respectively, except that they are called with a |
148 | .I va_list | |
149 | instead of a variable number of arguments. | |
c13182ef | 150 | These functions do not call the |
fea681da | 151 | .I va_end |
c13182ef | 152 | macro. |
f6b55d82 MK |
153 | Because they invoke the |
154 | .I va_arg | |
155 | macro, the value of | |
fea681da | 156 | .I ap |
c13182ef | 157 | is undefined after the call. |
f6b55d82 | 158 | See |
31b640cb | 159 | .BR stdarg (3). |
847e0d88 | 160 | .PP |
62730046 | 161 | All of these functions write the output under the control of a |
fea681da MK |
162 | .I format |
163 | string that specifies how subsequent arguments (or arguments accessed via | |
164 | the variable-length argument facilities of | |
165 | .BR stdarg (3)) | |
166 | are converted for output. | |
847e0d88 | 167 | .PP |
08f88257 MK |
168 | C99 and POSIX.1-2001 specify that the results are undefined if a call to |
169 | .BR sprintf (), | |
170 | .BR snprintf (), | |
171 | .BR vsprintf (), | |
172 | or | |
173 | .BR vsnprintf () | |
ed35aae6 | 174 | would cause copying to take place between objects that overlap |
08f88257 MK |
175 | (e.g., if the target string array and one of the supplied input arguments |
176 | refer to the same buffer). | |
177 | See NOTES. | |
73d8cece | 178 | .SS Format of the format string |
fea681da MK |
179 | The format string is a character string, beginning and ending |
180 | in its initial shift state, if any. | |
181 | The format string is composed of zero or more directives: ordinary | |
182 | characters (not | |
183 | .BR % ), | |
184 | which are copied unchanged to the output stream; | |
185 | and conversion specifications, each of which results in fetching zero or | |
c13182ef MK |
186 | more subsequent arguments. |
187 | Each conversion specification is introduced by | |
fea681da MK |
188 | the character |
189 | .BR % , | |
190 | and ends with a | |
191 | .IR "conversion specifier" . | |
192 | In between there may be (in this order) zero or more | |
193 | .IR flags , | |
194 | an optional minimum | |
195 | .IR "field width" , | |
196 | an optional | |
197 | .I precision | |
198 | and an optional | |
199 | .IR "length modifier" . | |
847e0d88 | 200 | .PP |
fea681da | 201 | The arguments must correspond properly (after type promotion) with the |
c13182ef MK |
202 | conversion specifier. |
203 | By default, the arguments are used in the order | |
bbdc3380 MK |
204 | given, where each \(aq*\(aq (see |
205 | .I "Field width" | |
206 | and | |
207 | .I Precision | |
208 | below) and each conversion specifier asks for the next | |
fea681da MK |
209 | argument (and it is an error if insufficiently many arguments are given). |
210 | One can also specify explicitly which argument is taken, | |
333a424b | 211 | at each place where an argument is required, by writing "%m$" instead |
c45660d7 | 212 | of \(aq%\(aq and "*m$" instead of \(aq*\(aq, |
c38fc25e | 213 | where the decimal integer \fIm\fP denotes |
fea681da | 214 | the position in the argument list of the desired argument, indexed starting |
c13182ef MK |
215 | from 1. |
216 | Thus, | |
bd191423 | 217 | .in +4n |
fea681da | 218 | .nf |
7295b7ed | 219 | |
bd191423 | 220 | printf("%*d", width, num); |
7295b7ed | 221 | |
fea681da | 222 | .fi |
bd191423 | 223 | .in |
fea681da | 224 | and |
bd191423 | 225 | .in +4n |
fea681da | 226 | .nf |
7295b7ed | 227 | |
bd191423 | 228 | printf("%2$*1$d", width, num); |
7295b7ed | 229 | |
fea681da | 230 | .fi |
bd191423 | 231 | .in |
c13182ef MK |
232 | are equivalent. |
233 | The second style allows repeated references to the | |
234 | same argument. | |
333a424b | 235 | The C99 standard does not include the style using \(aq$\(aq, |
008f1ecc | 236 | which comes from the Single UNIX Specification. |
c13182ef | 237 | If the style using |
333a424b | 238 | \(aq$\(aq is used, it must be used throughout for all conversions taking an |
fea681da | 239 | argument and all width and precision arguments, but it may be mixed |
79306ba1 | 240 | with "%%" formats, which do not consume an argument. |
c13182ef | 241 | There may be no |
333a424b | 242 | gaps in the numbers of arguments specified using \(aq$\(aq; for example, if |
fea681da MK |
243 | arguments 1 and 3 are specified, argument 2 must also be specified |
244 | somewhere in the format string. | |
847e0d88 | 245 | .PP |
333a424b | 246 | For some numeric conversions a radix character ("decimal point") or |
c13182ef MK |
247 | thousands' grouping character is used. |
248 | The actual character used | |
2f0af33b MK |
249 | depends on the |
250 | .B LC_NUMERIC | |
251 | part of the locale. | |
2b609f22 MK |
252 | (See |
253 | .BR setlocale (3).) | |
c13182ef | 254 | The POSIX locale |
333a424b | 255 | uses \(aq.\(aq as radix character, and does not have a grouping character. |
fea681da | 256 | Thus, |
a6e2f128 | 257 | .in +4n |
fea681da | 258 | .nf |
36306005 | 259 | |
333a424b | 260 | printf("%\(aq.2f", 1234567.89); |
36306005 | 261 | |
fea681da | 262 | .fi |
a6e2f128 | 263 | .in |
333a424b MK |
264 | results in "1234567.89" in the POSIX locale, in "1234567,89" in the |
265 | nl_NL locale, and in "1.234.567,89" in the da_DK locale. | |
5c1685bd | 266 | .SS Flag characters |
fea681da MK |
267 | The character % is followed by zero or more of the following flags: |
268 | .TP | |
269 | .B # | |
324633ae | 270 | The value should be converted to an "alternate form". |
fea681da | 271 | For |
0daa9e92 | 272 | .B o |
fea681da MK |
273 | conversions, the first character of the output string is made zero |
274 | (by prefixing a 0 if it was not zero already). | |
275 | For | |
276 | .B x | |
277 | and | |
278 | .B X | |
c7094399 | 279 | conversions, a nonzero result has the string "0x" (or "0X" for |
fea681da | 280 | .B X |
c13182ef MK |
281 | conversions) prepended to it. |
282 | For | |
fea681da MK |
283 | .BR a , |
284 | .BR A , | |
285 | .BR e , | |
286 | .BR E , | |
287 | .BR f , | |
288 | .BR F , | |
289 | .BR g , | |
290 | and | |
291 | .B G | |
292 | conversions, the result will always contain a decimal point, even if no | |
293 | digits follow it (normally, a decimal point appears in the results of those | |
c13182ef MK |
294 | conversions only if a digit follows). |
295 | For | |
fea681da MK |
296 | .B g |
297 | and | |
298 | .B G | |
299 | conversions, trailing zeros are not removed from the result as they would | |
300 | otherwise be. | |
301 | For other conversions, the result is undefined. | |
302 | .TP | |
303 | .B \&0 | |
c13182ef MK |
304 | The value should be zero padded. |
305 | For | |
fea681da MK |
306 | .BR d , |
307 | .BR i , | |
308 | .BR o , | |
309 | .BR u , | |
310 | .BR x , | |
311 | .BR X , | |
312 | .BR a , | |
313 | .BR A , | |
314 | .BR e , | |
315 | .BR E , | |
316 | .BR f , | |
317 | .BR F , | |
318 | .BR g , | |
319 | and | |
320 | .B G | |
321 | conversions, the converted value is padded on the left with zeros rather | |
322 | than blanks. | |
323 | If the | |
324 | .B \&0 | |
325 | and | |
326 | .B \- | |
327 | flags both appear, the | |
328 | .B \&0 | |
329 | flag is ignored. | |
330 | If a precision is given with a numeric conversion | |
b9d200ce | 331 | .RB ( d , |
fea681da MK |
332 | .BR i , |
333 | .BR o , | |
334 | .BR u , | |
335 | .BR x , | |
336 | and | |
337 | .BR X ), | |
338 | the | |
339 | .B \&0 | |
340 | flag is ignored. | |
341 | For other conversions, the behavior is undefined. | |
342 | .TP | |
343 | .B \- | |
344 | The converted value is to be left adjusted on the field boundary. | |
c13182ef | 345 | (The default is right justification.) |
aacd17b1 | 346 | The converted value is padded on the right with blanks, rather |
c13182ef MK |
347 | than on the left with blanks or zeros. |
348 | A | |
fea681da MK |
349 | .B \- |
350 | overrides a | |
351 | .B \&0 | |
352 | if both are given. | |
353 | .TP | |
333a424b | 354 | .B \(aq \(aq |
fea681da MK |
355 | (a space) A blank should be left before a positive number |
356 | (or empty string) produced by a signed conversion. | |
357 | .TP | |
358 | .B + | |
4897420e | 359 | A sign (+ or \-) should always be placed before a number produced by a signed |
c13182ef | 360 | conversion. |
a7676884 | 361 | By default, a sign is used only for negative numbers. |
c13182ef | 362 | A |
fea681da MK |
363 | .B + |
364 | overrides a space if both are used. | |
365 | .PP | |
f078c3fa MK |
366 | The five flag characters above are defined in the C99 standard. |
367 | The Single UNIX Specification specifies one further flag character. | |
c13182ef | 368 | .TP |
333a424b | 369 | .B \(aq |
fea681da | 370 | For decimal conversion |
b9d200ce | 371 | .RB ( i , |
fea681da MK |
372 | .BR d , |
373 | .BR u , | |
374 | .BR f , | |
375 | .BR F , | |
376 | .BR g , | |
377 | .BR G ) | |
378 | the output is to be grouped with thousands' grouping characters | |
c13182ef | 379 | if the locale information indicates any. |
2b609f22 MK |
380 | (See |
381 | .BR setlocale (3).) | |
c13182ef | 382 | Note that many versions of |
8478ee02 | 383 | .BR gcc (1) |
c13182ef | 384 | cannot parse this option and will issue a warning. |
f078c3fa MK |
385 | (SUSv2 did not |
386 | include \fI%\(aqF\fP, but SUSv3 added it.) | |
fea681da MK |
387 | .PP |
388 | glibc 2.2 adds one further flag character. | |
389 | .TP | |
390 | .B I | |
391 | For decimal integer conversion | |
b9d200ce | 392 | .RB ( i , |
fea681da MK |
393 | .BR d , |
394 | .BR u ) | |
395 | the output uses the locale's alternative output digits, if any. | |
396 | For example, since glibc 2.2.3 this will give Arabic-Indic digits | |
333a424b | 397 | in the Persian ("fa_IR") locale. |
fea681da | 398 | .\" outdigits keyword in locale file |
5c1685bd | 399 | .SS Field width |
c7094399 | 400 | An optional decimal digit string (with nonzero first digit) specifying |
c13182ef MK |
401 | a minimum field width. |
402 | If the converted value has fewer characters | |
fea681da MK |
403 | than the field width, it will be padded with spaces on the left |
404 | (or right, if the left-adjustment flag has been given). | |
333a424b MK |
405 | Instead of a decimal digit string one may write "*" or "*m$" |
406 | (for some decimal integer \fIm\fP) to specify that the field width | |
407 | is given in the next argument, or in the \fIm\fP-th argument, respectively, | |
fea681da MK |
408 | which must be of type |
409 | .IR int . | |
333a424b | 410 | A negative field width is taken as a \(aq\-\(aq flag followed by a |
fea681da | 411 | positive field width. |
c382a365 | 412 | In no case does a nonexistent or small field width cause truncation of a |
fea681da MK |
413 | field; if the result of a conversion is wider than the field width, the |
414 | field is expanded to contain the conversion result. | |
5c1685bd | 415 | .SS Precision |
333a424b | 416 | An optional precision, in the form of a period (\(aq.\(aq) followed by an |
fea681da | 417 | optional decimal digit string. |
333a424b | 418 | Instead of a decimal digit string one may write "*" or "*m$" |
c38fc25e MK |
419 | (for some decimal integer \fIm\fP) to specify that the precision |
420 | is given in the next argument, or in the \fIm\fP-th argument, respectively, | |
fea681da MK |
421 | which must be of type |
422 | .IR int . | |
abbcef30 | 423 | If the precision is given as just \(aq.\(aq, the precision is taken to |
533b9c5c MK |
424 | be zero. |
425 | A negative precision is taken as if the precision were omitted. | |
fea681da MK |
426 | This gives the minimum number of digits to appear for |
427 | .BR d , | |
428 | .BR i , | |
429 | .BR o , | |
430 | .BR u , | |
431 | .BR x , | |
432 | and | |
433 | .B X | |
434 | conversions, the number of digits to appear after the radix character for | |
435 | .BR a , | |
436 | .BR A , | |
437 | .BR e , | |
438 | .BR E , | |
439 | .BR f , | |
440 | and | |
441 | .B F | |
442 | conversions, the maximum number of significant digits for | |
443 | .B g | |
444 | and | |
445 | .B G | |
446 | conversions, or the maximum number of characters to be printed from a | |
447 | string for | |
448 | .B s | |
449 | and | |
450 | .B S | |
451 | conversions. | |
5c1685bd | 452 | .SS Length modifier |
333a424b | 453 | Here, "integer conversion" stands for |
fea681da MK |
454 | .BR d , |
455 | .BR i , | |
456 | .BR o , | |
457 | .BR u , | |
458 | .BR x , | |
459 | or | |
0daa9e92 | 460 | .B X |
fea681da MK |
461 | conversion. |
462 | .TP | |
463 | .B hh | |
464 | A following integer conversion corresponds to a | |
465 | .I signed char | |
466 | or | |
467 | .I unsigned char | |
468 | argument, or a following | |
469 | .B n | |
470 | conversion corresponds to a pointer to a | |
471 | .I signed char | |
472 | argument. | |
473 | .TP | |
474 | .B h | |
475 | A following integer conversion corresponds to a | |
476 | .I short int | |
477 | or | |
478 | .I unsigned short int | |
479 | argument, or a following | |
480 | .B n | |
481 | conversion corresponds to a pointer to a | |
482 | .I short int | |
483 | argument. | |
484 | .TP | |
485 | .B l | |
486 | (ell) A following integer conversion corresponds to a | |
487 | .I long int | |
488 | or | |
489 | .I unsigned long int | |
490 | argument, or a following | |
491 | .B n | |
492 | conversion corresponds to a pointer to a | |
493 | .I long int | |
494 | argument, or a following | |
495 | .B c | |
496 | conversion corresponds to a | |
497 | .I wint_t | |
498 | argument, or a following | |
499 | .B s | |
500 | conversion corresponds to a pointer to | |
501 | .I wchar_t | |
502 | argument. | |
503 | .TP | |
504 | .B ll | |
505 | (ell-ell). | |
506 | A following integer conversion corresponds to a | |
507 | .I long long int | |
508 | or | |
509 | .I unsigned long long int | |
510 | argument, or a following | |
511 | .B n | |
512 | conversion corresponds to a pointer to a | |
513 | .I long long int | |
514 | argument. | |
515 | .TP | |
74b9e29f MK |
516 | .B q |
517 | A synonym for | |
518 | .BR ll . | |
519 | This is a nonstandard extension, derived from BSD; | |
520 | avoid its use in new code. | |
521 | .TP | |
0daa9e92 | 522 | .B L |
fea681da MK |
523 | A following |
524 | .BR a , | |
525 | .BR A , | |
526 | .BR e , | |
527 | .BR E , | |
528 | .BR f , | |
529 | .BR F , | |
530 | .BR g , | |
531 | or | |
532 | .B G | |
533 | conversion corresponds to a | |
534 | .I long double | |
535 | argument. | |
536 | (C99 allows %LF, but SUSv2 does not.) | |
fea681da MK |
537 | .TP |
538 | .B j | |
539 | A following integer conversion corresponds to an | |
540 | .I intmax_t | |
541 | or | |
542 | .I uintmax_t | |
c271056c MK |
543 | argument, or a following |
544 | .B n | |
545 | conversion corresponds to a pointer to an | |
546 | .I intmax_t | |
fea681da MK |
547 | argument. |
548 | .TP | |
549 | .B z | |
550 | A following integer conversion corresponds to a | |
551 | .I size_t | |
552 | or | |
553 | .I ssize_t | |
c271056c MK |
554 | argument, or a following |
555 | .B n | |
556 | conversion corresponds to a pointer to a | |
557 | .I size_t | |
c13182ef | 558 | argument. |
1b8d3054 MK |
559 | .TP |
560 | .B Z | |
561 | A nonstandard synonym for | |
562 | .BR z | |
563 | that predates the appearance of | |
564 | .BR z . | |
565 | Do not use in new code. | |
fea681da MK |
566 | .TP |
567 | .B t | |
568 | A following integer conversion corresponds to a | |
569 | .I ptrdiff_t | |
c271056c MK |
570 | argument, or a following |
571 | .B n | |
572 | conversion corresponds to a pointer to a | |
573 | .I ptrdiff_t | |
fea681da MK |
574 | argument. |
575 | .PP | |
74b9e29f MK |
576 | SUSv3 specifies all of the above, |
577 | except for those modifiers explicitly noted as being nonstandard extensions. | |
f078c3fa | 578 | SUSv2 specified only the length modifiers |
fea681da MK |
579 | .B h |
580 | (in | |
581 | .BR hd , | |
582 | .BR hi , | |
583 | .BR ho , | |
584 | .BR hx , | |
585 | .BR hX , | |
586 | .BR hn ) | |
587 | and | |
588 | .B l | |
589 | (in | |
590 | .BR ld , | |
591 | .BR li , | |
592 | .BR lo , | |
593 | .BR lx , | |
594 | .BR lX , | |
595 | .BR ln , | |
596 | .BR lc , | |
597 | .BR ls ) | |
598 | and | |
599 | .B L | |
600 | (in | |
601 | .BR Le , | |
602 | .BR LE , | |
603 | .BR Lf , | |
604 | .BR Lg , | |
605 | .BR LG ). | |
847e0d88 | 606 | .PP |
5d717bda MK |
607 | As a nonstandard extension, the GNU implementations treats |
608 | .B ll | |
609 | and | |
610 | .B L | |
611 | as synonyms, so that one can, for example, write | |
612 | .BR llg | |
613 | (as a synonym for the standards-compliant | |
614 | .RB Lg ) | |
615 | and | |
616 | .BR Ld | |
617 | (as a synonym for the standards compliant | |
618 | .BR lld ). | |
619 | Such usage is nonportable. | |
620 | .\" | |
5c1685bd | 621 | .SS Conversion specifiers |
fea681da MK |
622 | A character that specifies the type of conversion to be applied. |
623 | The conversion specifiers and their meanings are: | |
624 | .TP | |
512c4c1a | 625 | .BR d ", " i |
fea681da MK |
626 | The |
627 | .I int | |
628 | argument is converted to signed decimal notation. | |
629 | The precision, if any, gives the minimum number of digits | |
630 | that must appear; if the converted value requires fewer digits, it is | |
c13182ef MK |
631 | padded on the left with zeros. |
632 | The default precision is 1. | |
fea681da MK |
633 | When 0 is printed with an explicit precision 0, the output is empty. |
634 | .TP | |
512c4c1a | 635 | .BR o ", " u ", " x ", " X |
fea681da MK |
636 | The |
637 | .I "unsigned int" | |
638 | argument is converted to unsigned octal | |
b9d200ce | 639 | .RB ( o ), |
fea681da | 640 | unsigned decimal |
b9d200ce | 641 | .RB ( u ), |
fea681da | 642 | or unsigned hexadecimal |
b9d200ce | 643 | .RB ( x |
fea681da MK |
644 | and |
645 | .BR X ) | |
c13182ef MK |
646 | notation. |
647 | The letters | |
fea681da MK |
648 | .B abcdef |
649 | are used for | |
650 | .B x | |
651 | conversions; the letters | |
652 | .B ABCDEF | |
653 | are used for | |
654 | .B X | |
c13182ef MK |
655 | conversions. |
656 | The precision, if any, gives the minimum number of digits | |
fea681da | 657 | that must appear; if the converted value requires fewer digits, it is |
c13182ef MK |
658 | padded on the left with zeros. |
659 | The default precision is 1. | |
fea681da MK |
660 | When 0 is printed with an explicit precision 0, the output is empty. |
661 | .TP | |
512c4c1a | 662 | .BR e ", " E |
fea681da MK |
663 | The |
664 | .I double | |
665 | argument is rounded and converted in the style | |
ee9d4801 | 666 | .RB [\-]d \&. ddd e \(+-dd |
ca5ac066 | 667 | where there is one digit before the decimal-point character and the number |
fea681da | 668 | of digits after it is equal to the precision; if the precision is missing, |
ca5ac066 | 669 | it is taken as 6; if the precision is zero, no decimal-point character |
c13182ef MK |
670 | appears. |
671 | An | |
fea681da MK |
672 | .B E |
673 | conversion uses the letter | |
674 | .B E | |
675 | (rather than | |
676 | .BR e ) | |
c13182ef MK |
677 | to introduce the exponent. |
678 | The exponent always contains at least two | |
fea681da MK |
679 | digits; if the value is zero, the exponent is 00. |
680 | .TP | |
512c4c1a | 681 | .BR f ", " F |
fea681da MK |
682 | The |
683 | .I double | |
684 | argument is rounded and converted to decimal notation in the style | |
b9d200ce | 685 | .RB [\-]ddd \&. ddd, |
ca5ac066 | 686 | where the number of digits after the decimal-point character is equal to |
c13182ef MK |
687 | the precision specification. |
688 | If the precision is missing, it is taken as | |
ca5ac066 | 689 | 6; if the precision is explicitly zero, no decimal-point character appears. |
fea681da | 690 | If a decimal point appears, at least one digit appears before it. |
847e0d88 | 691 | .IP |
f835f2c4 | 692 | (SUSv2 does not know about |
fea681da MK |
693 | .B F |
694 | and says that character string representations for infinity and NaN | |
c13182ef | 695 | may be made available. |
f078c3fa MK |
696 | SUSv3 adds a specification for |
697 | .BR F . | |
333a424b MK |
698 | The C99 standard specifies "[\-]inf" or "[\-]infinity" |
699 | for infinity, and a string starting with "nan" for NaN, in the case of | |
fea681da | 700 | .B f |
4a663059 | 701 | conversion, and "[\-]INF" or "[\-]INFINITY" or "NAN" in the case of |
fea681da MK |
702 | .B F |
703 | conversion.) | |
704 | .TP | |
512c4c1a | 705 | .BR g ", " G |
fea681da MK |
706 | The |
707 | .I double | |
708 | argument is converted in style | |
709 | .B f | |
710 | or | |
711 | .B e | |
712 | (or | |
713 | .B F | |
714 | or | |
715 | .B E | |
716 | for | |
717 | .B G | |
c13182ef MK |
718 | conversions). |
719 | The precision specifies the number of significant digits. | |
fea681da | 720 | If the precision is missing, 6 digits are given; if the precision is zero, |
c13182ef MK |
721 | it is treated as 1. |
722 | Style | |
fea681da MK |
723 | .B e |
724 | is used if the exponent from its conversion is less than \-4 or greater | |
c13182ef MK |
725 | than or equal to the precision. |
726 | Trailing zeros are removed from the | |
fea681da MK |
727 | fractional part of the result; a decimal point appears only if it is |
728 | followed by at least one digit. | |
729 | .TP | |
512c4c1a | 730 | .BR a ", " A |
f078c3fa MK |
731 | (C99; not in SUSv2, but added in SUSv3) |
732 | For | |
fea681da MK |
733 | .B a |
734 | conversion, the | |
735 | .I double | |
736 | argument is converted to hexadecimal notation (using the letters abcdef) | |
737 | in the style | |
ee9d4801 | 738 | .RB [\-] 0x h \&. hhhh p \(+-; |
fea681da MK |
739 | for |
740 | .B A | |
741 | conversion the prefix | |
742 | .BR 0X , | |
743 | the letters ABCDEF, and the exponent separator | |
744 | .B P | |
745 | is used. | |
746 | There is one hexadecimal digit before the decimal point, | |
747 | and the number of digits after it is equal to the precision. | |
748 | The default precision suffices for an exact representation of the value | |
749 | if an exact representation in base 2 exists | |
750 | and otherwise is sufficiently large to distinguish values of type | |
751 | .IR double . | |
24b74457 | 752 | The digit before the decimal point is unspecified for nonnormalized |
c7094399 | 753 | numbers, and nonzero but otherwise unspecified for normalized numbers. |
fea681da MK |
754 | .TP |
755 | .B c | |
756 | If no | |
757 | .B l | |
758 | modifier is present, the | |
759 | .I int | |
760 | argument is converted to an | |
761 | .IR "unsigned char" , | |
762 | and the resulting character is written. | |
763 | If an | |
764 | .B l | |
765 | modifier is present, the | |
766 | .I wint_t | |
767 | (wide character) argument is converted to a multibyte sequence by a call | |
768 | to the | |
fb186734 | 769 | .BR wcrtomb (3) |
fea681da MK |
770 | function, with a conversion state starting in the initial state, and the |
771 | resulting multibyte string is written. | |
772 | .TP | |
773 | .B s | |
774 | If no | |
775 | .B l | |
f64cc745 | 776 | modifier is present: the |
5049da5b | 777 | .I "const char\ *" |
fea681da | 778 | argument is expected to be a pointer to an array of character type (pointer |
c13182ef MK |
779 | to a string). |
780 | Characters from the array are written up to (but not | |
333a424b | 781 | including) a terminating null byte (\(aq\\0\(aq); |
28d88c17 | 782 | if a precision is specified, no more than the number specified |
c13182ef MK |
783 | are written. |
784 | If a precision is given, no null byte need be present; | |
fea681da | 785 | if the precision is not specified, or is greater than the size of the |
28d88c17 | 786 | array, the array must contain a terminating null byte. |
847e0d88 | 787 | .IP |
fea681da MK |
788 | If an |
789 | .B l | |
f64cc745 | 790 | modifier is present: the |
5049da5b | 791 | .I "const wchar_t\ *" |
fea681da MK |
792 | argument is expected to be a pointer to an array of wide characters. |
793 | Wide characters from the array are converted to multibyte characters | |
794 | (each by a call to the | |
fb186734 | 795 | .BR wcrtomb (3) |
fea681da MK |
796 | function, with a conversion state starting in the initial state before |
797 | the first wide character), up to and including a terminating null | |
c13182ef MK |
798 | wide character. |
799 | The resulting multibyte characters are written up to | |
800 | (but not including) the terminating null byte. | |
801 | If a precision is | |
fea681da | 802 | specified, no more bytes than the number specified are written, but |
c13182ef MK |
803 | no partial multibyte characters are written. |
804 | Note that the precision | |
fea681da MK |
805 | determines the number of |
806 | .I bytes | |
807 | written, not the number of | |
808 | .I wide characters | |
809 | or | |
810 | .IR "screen positions" . | |
811 | The array must contain a terminating null wide character, unless a | |
812 | precision is given and it is so small that the number of bytes written | |
813 | exceeds it before the end of the array is reached. | |
814 | .TP | |
815 | .B C | |
81204056 | 816 | (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) |
fea681da MK |
817 | Synonym for |
818 | .BR lc . | |
819 | Don't use. | |
820 | .TP | |
821 | .B S | |
81204056 | 822 | (Not in C99 or C11, but in SUSv2, SUSv3, and SUSv4.) |
fea681da MK |
823 | Synonym for |
824 | .BR ls . | |
825 | Don't use. | |
826 | .TP | |
827 | .B p | |
828 | The | |
5049da5b | 829 | .I "void\ *" |
fea681da MK |
830 | pointer argument is printed in hexadecimal (as if by |
831 | .B %#x | |
832 | or | |
edcf162e | 833 | .BR %#lx ). |
fea681da MK |
834 | .TP |
835 | .B n | |
836 | The number of characters written so far is stored into the integer | |
aacd17b1 MK |
837 | pointed to by the corresponding argument. |
838 | That argument shall be an | |
bafaef21 | 839 | .IR "int\ *" , |
aacd17b1 MK |
840 | or variant whose size matches the (optionally) |
841 | supplied integer length modifier. | |
c13182ef | 842 | No argument is converted. |
2974f405 | 843 | (This specifier is not supported by the bionic C library.) |
aacd17b1 MK |
844 | The behavior is undefined if the conversion specification includes |
845 | any flags, a field width, or a precision. | |
c13182ef | 846 | .TP |
c15f96dd | 847 | .B m |
2974f405 | 848 | (Glibc extension; supported by uClibc and musl.) |
c13182ef | 849 | Print output of |
c15f96dd MK |
850 | .IR strerror(errno) . |
851 | No argument is required. | |
fea681da MK |
852 | .TP |
853 | .B % | |
333a424b | 854 | A \(aq%\(aq is written. |
c13182ef MK |
855 | No argument is converted. |
856 | The complete conversion | |
333a424b | 857 | specification is \(aq%%\(aq. |
648fdb79 MK |
858 | .SH RETURN VALUE |
859 | Upon successful return, these functions return the number of characters | |
860 | printed (excluding the null byte used to end output to strings). | |
847e0d88 | 861 | .PP |
648fdb79 MK |
862 | The functions |
863 | .BR snprintf () | |
864 | and | |
865 | .BR vsnprintf () | |
866 | do not write more than | |
867 | .I size | |
868 | bytes (including the terminating null byte (\(aq\e0\(aq)). | |
869 | If the output was truncated due to this limit, then the return value | |
870 | is the number of characters (excluding the terminating null byte) | |
871 | which would have been written to the final string if enough space | |
872 | had been available. | |
873 | Thus, a return value of | |
874 | .I size | |
875 | or more means that the output was truncated. | |
876 | (See also below under NOTES.) | |
847e0d88 | 877 | .PP |
648fdb79 | 878 | If an output error is encountered, a negative value is returned. |
1567901b ZL |
879 | .SH ATTRIBUTES |
880 | For an explanation of the terms used in this section, see | |
881 | .BR attributes (7). | |
882 | .TS | |
883 | allbox; | |
884 | lbw23 lb lb | |
885 | l l l. | |
886 | Interface Attribute Value | |
887 | T{ | |
888 | .BR printf (), | |
889 | .BR fprintf (), | |
890 | .br | |
891 | .BR sprintf (), | |
892 | .BR snprintf (), | |
893 | .br | |
894 | .BR vprintf (), | |
895 | .BR vfprintf (), | |
896 | .br | |
897 | .BR vsprintf (), | |
898 | .BR vsnprintf () | |
899 | T} Thread safety MT-Safe locale | |
900 | .TE | |
847e0d88 | 901 | .sp 1 |
47297adb | 902 | .SH CONFORMING TO |
e511ffb6 MK |
903 | .BR fprintf (), |
904 | .BR printf (), | |
905 | .BR sprintf (), | |
906 | .BR vprintf (), | |
907 | .BR vfprintf (), | |
e3bfeae0 MK |
908 | .BR vsprintf (): |
909 | POSIX.1-2001, POSIX.1-2008, C89, C99. | |
847e0d88 | 910 | .PP |
e3bfeae0 MK |
911 | .BR snprintf (), |
912 | .BR vsnprintf (): | |
913 | POSIX.1-2001, POSIX.1-2008, C99. | |
847e0d88 | 914 | .PP |
db39a679 MK |
915 | The |
916 | .BR dprintf () | |
917 | and | |
918 | .BR vdprintf () | |
919 | functions were originally GNU extensions that were later standardized | |
920 | in POSIX.1-2008. | |
fea681da MK |
921 | .PP |
922 | Concerning the return value of | |
e511ffb6 | 923 | .BR snprintf (), |
68e1685c | 924 | SUSv2 and C99 contradict each other: when |
e511ffb6 | 925 | .BR snprintf () |
fea681da MK |
926 | is called with |
927 | .IR size =0 | |
928 | then SUSv2 stipulates an unspecified return value less than 1, | |
929 | while C99 allows | |
930 | .I str | |
931 | to be NULL in this case, and gives the return value (as always) | |
932 | as the number of characters that would have been written in case | |
933 | the output string has been large enough. | |
e3bfeae0 | 934 | POSIX.1-2001 and later align their specification of |
588d27ea MK |
935 | .BR snprintf () |
936 | with C99. | |
7905872b MK |
937 | .\" .PP |
938 | .\" Linux libc4 knows about the five C standard flags. | |
939 | .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, | |
940 | .\" and the conversions | |
941 | .\" \fBc\fP, \fBd\fP, \fBe\fP, \fBE\fP, \fBf\fP, \fBF\fP, | |
942 | .\" \fBg\fP, \fBG\fP, \fBi\fP, \fBn\fP, \fBo\fP, \fBp\fP, | |
943 | .\" \fBs\fP, \fBu\fP, \fBx\fP, and \fBX\fP, | |
944 | .\" where \fBF\fP is a synonym for \fBf\fP. | |
945 | .\" Additionally, it accepts \fBD\fP, \fBO\fP, and \fBU\fP as synonyms | |
946 | .\" for \fBld\fP, \fBlo\fP, and \fBlu\fP. | |
947 | .\" (This is bad, and caused serious bugs later, when | |
948 | .\" support for \fB%D\fP disappeared.) | |
949 | .\" No locale-dependent radix character, | |
950 | .\" no thousands' separator, no NaN or infinity, no "%m$" and "*m$". | |
951 | .\" .PP | |
952 | .\" Linux libc5 knows about the five C standard flags and the \(aq flag, | |
953 | .\" locale, "%m$" and "*m$". | |
954 | .\" It knows about the length modifiers \fBh\fP, \fBl\fP, \fBL\fP, | |
955 | .\" \fBZ\fP, and \fBq\fP, but accepts \fBL\fP and \fBq\fP | |
956 | .\" both for \fIlong double\fP and for \fIlong long int\fP (this is a bug). | |
957 | .\" It no longer recognizes \fBF\fP, \fBD\fP, \fBO\fP, and \fBU\fP, | |
958 | .\" but adds the conversion character | |
959 | .\" .BR m , | |
960 | .\" which outputs | |
961 | .\" .IR strerror(errno) . | |
5afad698 MK |
962 | .\" .PP |
963 | .\" glibc 2.0 adds conversion characters \fBC\fP and \fBS\fP. | |
fea681da | 964 | .PP |
512c4c1a | 965 | glibc 2.1 adds length modifiers \fBhh\fP, \fBj\fP, \fBt\fP, and \fBz\fP |