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