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