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