Rev 4874 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
4349 | Serge | 1 | /* |
2 | * Copyright (c) 1990 The Regents of the University of California. |
||
3 | * All rights reserved. |
||
4 | * |
||
5 | * Redistribution and use in source and binary forms are permitted |
||
6 | * provided that the above copyright notice and this paragraph are |
||
7 | * duplicated in all such forms and that any documentation, |
||
8 | * advertising materials, and other materials related to such |
||
9 | * distribution and use acknowledge that the software was developed |
||
10 | * by the University of California, Berkeley. The name of the |
||
11 | * University may not be used to endorse or promote products derived |
||
12 | * from this software without specific prior written permission. |
||
13 | * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR |
||
14 | * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED |
||
15 | * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
||
16 | */ |
||
17 | |||
18 | /* |
||
19 | FUNCTION |
||
20 | < |
||
21 | |||
22 | INDEX |
||
23 | fprintf |
||
24 | INDEX |
||
25 | _fprintf_r |
||
26 | INDEX |
||
27 | printf |
||
28 | INDEX |
||
29 | _printf_r |
||
30 | INDEX |
||
31 | asprintf |
||
32 | INDEX |
||
33 | _asprintf_r |
||
34 | INDEX |
||
35 | sprintf |
||
36 | INDEX |
||
37 | _sprintf_r |
||
38 | INDEX |
||
39 | snprintf |
||
40 | INDEX |
||
41 | _snprintf_r |
||
42 | INDEX |
||
43 | asnprintf |
||
44 | INDEX |
||
45 | _asnprintf_r |
||
46 | |||
47 | ANSI_SYNOPSIS |
||
48 | #include |
||
49 | |||
4921 | Serge | 50 | int printf(const char *restrict <[format]>, ...); |
51 | int fprintf(FILE *restrict <[fd]>, const char *restrict <[format]>, ...); |
||
52 | int sprintf(char *restrict <[str]>, const char *restrict <[format]>, ...); |
||
53 | int snprintf(char *restrict <[str]>, size_t <[size]>, const char *restrict <[format]>, |
||
4349 | Serge | 54 | ...); |
4921 | Serge | 55 | int asprintf(char **restrict <[strp]>, const char *restrict <[format]>, ...); |
56 | char *asnprintf(char *restrict <[str]>, size_t *restrict <[size]>, const char *restrict <[format]>, |
||
4349 | Serge | 57 | ...); |
58 | |||
4921 | Serge | 59 | int _printf_r(struct _reent *<[ptr]>, const char *restrict <[format]>, ...); |
60 | int _fprintf_r(struct _reent *<[ptr]>, FILE *restrict <[fd]>, |
||
61 | const char *restrict <[format]>, ...); |
||
62 | int _sprintf_r(struct _reent *<[ptr]>, char *restrict <[str]>, |
||
63 | const char *restrict <[format]>, ...); |
||
64 | int _snprintf_r(struct _reent *<[ptr]>, char *restrict <[str]>, size_t <[size]>, |
||
65 | const char *restrict <[format]>, ...); |
||
66 | int _asprintf_r(struct _reent *<[ptr]>, char **restrict <[strp]>, |
||
67 | const char *restrict <[format]>, ...); |
||
68 | char *_asnprintf_r(struct _reent *<[ptr]>, char *restrict <[str]>, |
||
69 | size_t *restrict <[size]>, const char *restrict <[format]>, ...); |
||
4349 | Serge | 70 | |
71 | DESCRIPTION |
||
72 | < |
||
73 | format specifier from <<*<[format]>>>, and writes the |
||
74 | formatted data to < |
||
75 | character. The behavior of < |
||
76 | are not enough arguments for the format. < |
||
77 | when it reaches the end of the format string. If there are |
||
78 | more arguments than the format requires, excess arguments are |
||
79 | ignored. |
||
80 | |||
81 | < |
||
82 | to the stream <[fd]> rather than < |
||
83 | |||
84 | < |
||
85 | to the buffer <[str]>, and a terminating NUL is output. |
||
86 | Behavior is undefined if more output is generated than the |
||
87 | buffer can hold. |
||
88 | |||
89 | < |
||
90 | limited to at most <[size]> bytes, including the terminating |
||
91 | < |
||
92 | NULL, and < |
||
93 | be printed. |
||
94 | |||
95 | < |
||
96 | stored in a dynamically allocated buffer, <[pstr]>, which |
||
97 | should be freed later with < |
||
98 | |||
99 | < |
||
100 | is either the original <[str]> if it was large enough, or a |
||
101 | dynamically allocated string if the output exceeds *<[size]>; |
||
102 | the length of the result is returned in *<[size]>. When |
||
103 | dynamic allocation occurs, the contents of the original |
||
104 | <[str]> may have been modified. |
||
105 | |||
106 | For < |
||
107 | is undefined if the output <<*<[str]>>> overlaps with one of |
||
108 | the arguments. Behavior is also undefined if the argument for |
||
109 | <<%n>> within <<*<[format]>>> overlaps another argument. |
||
110 | |||
111 | <[format]> is a pointer to a character string containing two |
||
112 | types of objects: ordinary characters (other than <<%>>), |
||
113 | which are copied unchanged to the output, and conversion |
||
114 | specifications, each of which is introduced by <<%>>. (To |
||
115 | include <<%>> in the output, use <<%%>> in the format string.) |
||
116 | A conversion specification has the following form: |
||
117 | |||
118 | . %[<[pos]>][<[flags]>][<[width]>][.<[prec]>][<[size]>]<[type]> |
||
119 | |||
120 | The fields of the conversion specification have the following |
||
121 | meanings: |
||
122 | |||
123 | O+ |
||
124 | o <[pos]> |
||
125 | |||
126 | Conversions normally consume arguments in the order that they |
||
127 | are presented. However, it is possible to consume arguments |
||
128 | out of order, and reuse an argument for more than one |
||
129 | conversion specification (although the behavior is undefined |
||
130 | if the same argument is requested with different types), by |
||
131 | specifying <[pos]>, which is a decimal integer followed by |
||
132 | '$'. The integer must be between 1 and |
||
133 | limits.h, and if argument <<%n$>> is requested, all earlier |
||
134 | arguments must be requested somewhere within <[format]>. If |
||
135 | positional parameters are used, then all conversion |
||
136 | specifications except for <<%%>> must specify a position. |
||
137 | This positional parameters method is a POSIX extension to the C |
||
138 | standard definition for the functions. |
||
139 | |||
140 | o <[flags]> |
||
141 | |||
142 | <[flags]> is an optional sequence of characters which control |
||
143 | output justification, numeric signs, decimal points, trailing |
||
144 | zeros, and octal and hex prefixes. The flag characters are |
||
145 | minus (<<->>), plus (<<+>>), space ( ), zero (<<0>>), sharp |
||
146 | (<<#>>), and quote (<<'>>). They can appear in any |
||
147 | combination, although not all flags can be used for all |
||
148 | conversion specification types. |
||
149 | |||
150 | o+ |
||
151 | o ' |
||
152 | A POSIX extension to the C standard. However, this |
||
153 | implementation presently treats it as a no-op, which |
||
154 | is the default behavior for the C locale, anyway. (If |
||
155 | it did what it is supposed to, when <[type]> were <>, |
||
156 | < |
||
157 | integer portion of the conversion would be formatted |
||
158 | with thousands' grouping wide characters.) |
||
159 | |||
160 | o - |
||
161 | The result of the conversion is left |
||
162 | justified, and the right is padded with |
||
163 | blanks. If you do not use this flag, the |
||
164 | result is right justified, and padded on the |
||
165 | left. |
||
166 | |||
167 | o + |
||
168 | The result of a signed conversion (as |
||
169 | determined by <[type]> of < |
||
170 | <>, < |
||
171 | < |
||
172 | sign. (If you do not use this flag, positive |
||
173 | values do not begin with a plus sign.) |
||
174 | |||
175 | o " " (space) |
||
176 | If the first character of a signed conversion |
||
177 | specification is not a sign, or if a signed |
||
178 | conversion results in no characters, the |
||
179 | result will begin with a space. If the space |
||
180 | ( ) flag and the plus (<<+>>) flag both |
||
181 | appear, the space flag is ignored. |
||
182 | |||
183 | o 0 |
||
184 | If the <[type]> character is < |
||
185 | < |
||
186 | < |
||
187 | zeros are used to pad the field width |
||
188 | (following any indication of sign or base); no |
||
189 | spaces are used for padding. If the zero |
||
190 | (<<0>>) and minus (<<->>) flags both appear, |
||
191 | the zero (<<0>>) flag will be ignored. For |
||
192 | < |
||
193 | conversions, if a precision <[prec]> is |
||
194 | specified, the zero (<<0>>) flag is ignored. |
||
195 | |||
196 | Note that <<0>> is interpreted as a flag, not |
||
197 | as the beginning of a field width. |
||
198 | |||
199 | o # |
||
200 | The result is to be converted to an |
||
201 | alternative form, according to the <[type]> |
||
202 | character: |
||
203 | |||
204 | o+ |
||
205 | o o |
||
206 | Increases precision to force the first |
||
207 | digit of the result to be a zero. |
||
208 | |||
209 | o x |
||
210 | A non-zero result will have a <<0x>> |
||
211 | prefix. |
||
212 | |||
213 | o X |
||
214 | A non-zero result will have a <<0X>> |
||
215 | prefix. |
||
216 | |||
217 | o a, A, e, E, f, or F |
||
218 | The result will always contain a |
||
219 | decimal point even if no digits follow |
||
220 | the point. (Normally, a decimal point |
||
221 | appears only if a digit follows it.) |
||
222 | Trailing zeros are removed. |
||
223 | |||
224 | o g or G |
||
225 | The result will always contain a |
||
226 | decimal point even if no digits follow |
||
227 | the point. Trailing zeros are not |
||
228 | removed. |
||
229 | |||
230 | o all others |
||
231 | Undefined. |
||
232 | |||
233 | o- |
||
234 | o- |
||
235 | |||
236 | o <[width]> |
||
237 | |||
238 | <[width]> is an optional minimum field width. You can |
||
239 | either specify it directly as a decimal integer, or |
||
240 | indirectly by using instead an asterisk (<<*>>), in |
||
241 | which case an < |
||
242 | width. If positional arguments are used, then the |
||
243 | width must also be specified positionally as <<*m$>>, |
||
244 | with m as a decimal integer. Negative field widths |
||
245 | are treated as specifying the minus (<<->>) flag for |
||
246 | left justfication, along with a positive field width. |
||
247 | The resulting format may be wider than the specified |
||
248 | width. |
||
249 | |||
250 | o <[prec]> |
||
251 | |||
252 | <[prec]> is an optional field; if present, it is |
||
253 | introduced with `<<.>>' (a period). You can specify |
||
254 | the precision either directly as a decimal integer or |
||
255 | indirectly by using an asterisk (<<*>>), in which case |
||
256 | an < |
||
257 | positional arguments are used, then the precision must |
||
258 | also be specified positionally as <<*m$>>, with m as a |
||
259 | decimal integer. Supplying a negative precision is |
||
260 | equivalent to omitting the precision. If only a |
||
261 | period is specified the precision is zero. The effect |
||
262 | depends on the conversion <[type]>. |
||
263 | |||
264 | o+ |
||
265 | o d, i, o, u, x, or X |
||
266 | Minimum number of digits to appear. If no |
||
267 | precision is given, defaults to 1. |
||
268 | |||
269 | o a or A |
||
270 | Number of digits to appear after the decimal |
||
271 | point. If no precision is given, the |
||
272 | precision defaults to the minimum needed for |
||
273 | an exact representation. |
||
274 | |||
275 | o e, E, f or F |
||
276 | Number of digits to appear after the decimal |
||
277 | point. If no precision is given, the |
||
278 | precision defaults to 6. |
||
279 | |||
280 | o g or G |
||
281 | Maximum number of significant digits. A |
||
282 | precision of 0 is treated the same as a |
||
283 | precision of 1. If no precision is given, the |
||
284 | precision defaults to 6. |
||
285 | |||
286 | o s or S |
||
287 | Maximum number of characters to print from the |
||
288 | string. If no precision is given, the entire |
||
289 | string is printed. |
||
290 | |||
291 | o all others |
||
292 | undefined. |
||
293 | |||
294 | o- |
||
295 | |||
296 | o <[size]> |
||
297 | |||
298 | <[size]> is an optional modifier that changes the data |
||
299 | type that the corresponding argument has. Behavior is |
||
300 | unspecified if a size is given that does not match the |
||
301 | <[type]>. |
||
302 | |||
303 | o+ |
||
304 | o hh |
||
305 | With < |
||
306 | < |
||
307 | converted to a < |
||
308 | char>> before printing. |
||
309 | |||
310 | With < |
||
311 | pointer to a < |
||
312 | |||
313 | o h |
||
314 | With < |
||
315 | < |
||
316 | converted to a < |
||
317 | before printing. |
||
318 | |||
319 | With < |
||
320 | pointer to a < |
||
321 | |||
322 | o l |
||
323 | With < |
||
324 | < |
||
325 | < |
||
326 | |||
327 | With < |
||
328 | type < |
||
329 | |||
330 | With < |
||
331 | pointer to < |
||
332 | |||
333 | With < |
||
334 | pointer to a < |
||
335 | |||
336 | With <>, <>, < |
||
337 | < |
||
338 | vararg promotion rules, there is no need to |
||
339 | distinguish between < |
||
340 | |||
341 | o ll |
||
342 | With < |
||
343 | < |
||
344 | < |
||
345 | |||
346 | With < |
||
347 | pointer to a < |
||
348 | |||
349 | o j |
||
350 | With < |
||
351 | < |
||
352 | < |
||
353 | |||
354 | With < |
||
355 | pointer to an < |
||
356 | |||
357 | o z |
||
358 | With < |
||
359 | < |
||
360 | |||
361 | With < |
||
362 | pointer to a < |
||
363 | |||
364 | o t |
||
365 | With < |
||
366 | < |
||
367 | < |
||
368 | |||
369 | With < |
||
370 | pointer to a < |
||
371 | |||
372 | o L |
||
373 | With <>, <>, < |
||
374 | < |
||
375 | is a < |
||
376 | |||
377 | o- |
||
378 | |||
379 | o <[type]> |
||
380 | |||
381 | <[type]> specifies what kind of conversion < |
||
382 | performs. Here is a table of these: |
||
383 | |||
384 | o+ |
||
385 | o % |
||
386 | Prints the percent character (<<%>>). |
||
387 | |||
388 | o c |
||
389 | Prints <[arg]> as single character. If the |
||
390 | < |
||
391 | character is printed. |
||
392 | |||
393 | o C |
||
394 | Short for <<%lc>>. A POSIX extension to the C standard. |
||
395 | |||
396 | o s |
||
397 | Prints the elements of a pointer to < |
||
398 | until the precision or a null character is |
||
399 | reached. If the < |
||
400 | effect, the pointer is to an array of |
||
401 | < |
||
402 | multibyte characters before printing. |
||
403 | |||
404 | o S |
||
405 | Short for <<%ls>>. A POSIX extension to the C standard. |
||
406 | |||
407 | o d or i |
||
408 | Prints a signed decimal integer; takes an |
||
409 | < |
||
410 | necessary to reach the precision. A value of 0 with |
||
411 | a precision of 0 produces an empty string. |
||
412 | |||
413 | o D |
||
414 | Newlib extension, short for <<%ld>>. |
||
415 | |||
416 | o o |
||
417 | Prints an unsigned octal integer; takes an |
||
418 | < |
||
419 | necessary to reach the precision. A value of 0 with |
||
420 | a precision of 0 produces an empty string. |
||
421 | |||
422 | o O |
||
423 | Newlib extension, short for <<%lo>>. |
||
424 | |||
425 | o u |
||
426 | Prints an unsigned decimal integer; takes an |
||
427 | < |
||
428 | necessary to reach the precision. A value of 0 with |
||
429 | a precision of 0 produces an empty string. |
||
430 | |||
431 | o U |
||
432 | Newlib extension, short for <<%lu>>. |
||
433 | |||
434 | o x |
||
435 | Prints an unsigned hexadecimal integer (using |
||
436 | < |
||
437 | < |
||
438 | necessary to reach the precision. A value of 0 with |
||
439 | a precision of 0 produces an empty string. |
||
440 | |||
441 | o X |
||
442 | Like < |
||
443 | beyond <<9>>. |
||
444 | |||
445 | o f |
||
446 | Prints a signed value of the form |
||
447 | <<[-]9999.9999>>, with the precision |
||
448 | determining how many digits follow the decimal |
||
449 | point; takes a < |
||
450 | < |
||
451 | The low order digit is rounded to even. If |
||
452 | the precision results in at most DECIMAL_DIG |
||
453 | digits, the result is rounded correctly; if |
||
454 | more than DECIMAL_DIG digits are printed, the |
||
455 | result is only guaranteed to round back to the |
||
456 | original value. |
||
457 | |||
458 | If the value is infinite, the result is |
||
459 | < |
||
460 | the value is not a number, the result is |
||
461 | < |
||
462 | |||
463 | o F |
||
464 | Like < |
||
465 | non-finite numbers. |
||
466 | |||
467 | o e |
||
468 | Prints a signed value of the form |
||
469 | <<[-]9.9999e[+|-]999>>; takes a < |
||
470 | The digit before the decimal point is non-zero |
||
471 | if the value is non-zero. The precision |
||
472 | determines how many digits appear between |
||
473 | <<.>> and < |
||
474 | contains at least two digits. The value zero |
||
475 | has an exponent of zero. If the value is not |
||
476 | finite, it is printed like < |
||
477 | |||
478 | o E |
||
479 | Like < |
||
480 | exponent, and like < |
||
481 | values. |
||
482 | |||
483 | o g |
||
484 | Prints a signed value in either < |
||
485 | form, based on the given value and |
||
486 | precision---an exponent less than -4 or |
||
487 | greater than the precision selects the < |
||
488 | form. Trailing zeros and the decimal point |
||
489 | are printed only if necessary; takes a |
||
490 | < |
||
491 | |||
492 | o G |
||
493 | Like < |
||
494 | |||
495 | o a |
||
496 | Prints a signed value of the form |
||
497 | <<[-]0x1.ffffp[+|-]9>>; takes a < |
||
498 | The letters < |
||
499 | beyond <<9>>. The precision determines how |
||
500 | many digits appear after the decimal point. |
||
501 | The exponent contains at least one digit, and |
||
502 | is a decimal value representing the power of |
||
503 | 2; a value of 0 has an exponent of 0. |
||
504 | Non-finite values are printed like < |
||
505 | |||
506 | o A |
||
507 | Like <>, except uses < |
||
508 | < |
||
509 | |||
510 | o n |
||
511 | Takes a pointer to < |
||
512 | of the number of bytes written so far. No |
||
513 | output is created. |
||
514 | |||
515 | o p |
||
516 | Takes a pointer to < |
||
517 | an implementation-defined format. This |
||
518 | implementation is similar to <<%#tx>>), except |
||
519 | that <<0x>> appears even for the NULL pointer. |
||
520 | |||
4921 | Serge | 521 | o m |
522 | Prints the output of < |
||
523 | argument is required. A GNU extension. |
||
524 | |||
4349 | Serge | 525 | o- |
526 | O- |
||
527 | |||
528 | <<_printf_r>>, <<_fprintf_r>>, <<_asprintf_r>>, |
||
529 | <<_sprintf_r>>, <<_snprintf_r>>, <<_asnprintf_r>> are simply |
||
530 | reentrant versions of the functions above. |
||
531 | |||
532 | RETURNS |
||
533 | On success, < |
||
534 | the output string, except the concluding < |
||
535 | < |
||
536 | string, except the concluding < |
||
537 | < |
||
538 | < |
||
539 | otherwise it returns an allocated string. |
||
540 | |||
541 | If an error occurs, the result of < |
||
542 | < |
||
543 | < |
||
544 | < |
||
545 | < |
||
546 | to ENOMEM if allocation fails, and for < |
||
547 | set to EOVERFLOW if <[size]> or the output length exceeds INT_MAX. |
||
548 | |||
549 | BUGS |
||
550 | The ``''' (quote) flag does not work when locale's thousands_sep is not empty. |
||
551 | |||
552 | PORTABILITY |
||
553 | ANSI C requires < |
||
554 | < |
||
555 | |||
556 | The ANSI C standard specifies that implementations must support at |
||
557 | least formatted output of up to 509 characters. This implementation |
||
558 | has no inherent limit. |
||
559 | |||
560 | Depending on how newlib was configured, not all format specifiers are |
||
561 | supported. |
||
562 | |||
563 | Supporting OS subroutines required: < |
||
564 | < |
||
565 | */ |
||
566 | |||
567 | #include <_ansi.h> |
||
568 | #include |
||
569 | #include |
||
570 | #ifdef _HAVE_STDC |
||
571 | #include |
||
572 | #else |
||
573 | #include |
||
574 | #endif |
||
575 | #include |
||
576 | #include "local.h" |
||
577 | |||
578 | int |
||
579 | #ifdef _HAVE_STDC |
||
580 | _DEFUN(_sprintf_r, (ptr, str, fmt), |
||
581 | struct _reent *ptr _AND |
||
4921 | Serge | 582 | char *__restrict str _AND |
583 | _CONST char *__restrict fmt _DOTS) |
||
4349 | Serge | 584 | #else |
585 | _sprintf_r(ptr, str, fmt, va_alist) |
||
586 | struct _reent *ptr; |
||
4921 | Serge | 587 | char *__restrict str; |
588 | _CONST char *__restrict fmt; |
||
4349 | Serge | 589 | va_dcl |
590 | #endif |
||
591 | { |
||
592 | int ret; |
||
593 | va_list ap; |
||
594 | FILE f; |
||
595 | |||
596 | f._flags = __SWR | __SSTR; |
||
597 | f._bf._base = f._p = (unsigned char *) str; |
||
598 | f._bf._size = f._w = INT_MAX; |
||
599 | f._file = -1; /* No file. */ |
||
600 | #ifdef _HAVE_STDC |
||
601 | va_start (ap, fmt); |
||
602 | #else |
||
603 | va_start (ap); |
||
604 | #endif |
||
605 | ret = _svfprintf_r (ptr, &f, fmt, ap); |
||
606 | va_end (ap); |
||
607 | *f._p = '\0'; /* terminate the string */ |
||
608 | return (ret); |
||
609 | } |
||
610 | |||
611 | #ifndef _REENT_ONLY |
||
612 | |||
613 | int |
||
614 | #ifdef _HAVE_STDC |
||
615 | _DEFUN(sprintf, (str, fmt), |
||
4921 | Serge | 616 | char *__restrict str _AND |
617 | _CONST char *__restrict fmt _DOTS) |
||
4349 | Serge | 618 | #else |
619 | sprintf(str, fmt, va_alist) |
||
620 | char *str; |
||
621 | _CONST char *fmt; |
||
622 | va_dcl |
||
623 | #endif |
||
624 | { |
||
625 | int ret; |
||
626 | va_list ap; |
||
627 | FILE f; |
||
628 | |||
629 | f._flags = __SWR | __SSTR; |
||
630 | f._bf._base = f._p = (unsigned char *) str; |
||
631 | f._bf._size = f._w = INT_MAX; |
||
632 | f._file = -1; /* No file. */ |
||
633 | #ifdef _HAVE_STDC |
||
634 | va_start (ap, fmt); |
||
635 | #else |
||
636 | va_start (ap); |
||
637 | #endif |
||
638 | ret = _svfprintf_r (_REENT, &f, fmt, ap); |
||
639 | va_end (ap); |
||
640 | *f._p = '\0'; /* terminate the string */ |
||
641 | return (ret); |
||
642 | } |
||
643 | |||
644 | #endif |