1 /*************************************************************************
3 * $Id: doc_printf.h,v 1.5 2008/10/12 12:09:51 breese Exp $
5 * Copyright (C) 2001 Bjorn Reese and Daniel Stenberg.
7 * Permission to use, copy, modify, and distribute this software for any
8 * purpose with or without fee is hereby granted, provided that the above
9 * copyright notice and this permission notice appear in all copies.
11 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
12 * WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
13 * MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE AUTHORS AND
14 * CONTRIBUTORS ACCEPT NO RESPONSIBILITY IN ANY CONCEIVABLE MANNER.
16 ************************************************************************/
18 /** @addtogroup Printf Formatted Printing Functions.
19 Variations of formatted printing functions.
31 This documentation is incomplete.
32 The documentation of the printf family in [C99] and [UNIX98] also applies
33 to the trio counterparts.
35 All these functions outputs a string which is formatted according to the
36 @p format string and the consecutive arguments. The @p format string is
37 described in the Formatting section below.
39 @ref trio_printf, @ref trio_vprintf, and @ref trio_printfv writes the
40 output to the standard output stream (stdout).
42 @ref trio_fprintf, @ref trio_vfprintf, and @ref trio_fprintfv writes the
43 output to a given output stream.
45 @ref trio_dprintf, @ref trio_vdprintf, and @ref trio_dprintfv writes the
46 output to a file descriptor (this includes, for example, sockets).
48 @ref trio_sprintf, @ref trio_vsprintf, and @ref trio_sprintfv writes the
49 output into @p buffer.
51 @ref trio_snprintf, @ref trio_vsnprintf, and @ref trio_snprintfv writes @p
52 max - 1 characters into @p buffer followed by a terminating zero character.
53 If @p max is 1, then @p buffer will be an empty string. If @p max is 0,
54 then @p buffer is left untouched, and can consequently be NULL. The number
55 of characters that would have been written to @p buffer, had there been
56 sufficient space, is returned.
58 @ref trio_snprintfcat appends the formatted text at the end of @p buffer.
60 @ref trio_asprintf, @ref trio_vasprintf, and @ref trio_asprintfv allocates
61 and returns an allocated string in @p buffer containing the formatted text.
65 The @p format string can contain normal text and conversion indicators.
66 The normal text can be any character except the nil character (\000 =
67 '\0') and the percent character (\045 = '%'). Conversion indicators
68 consists of an indication character (%), followed by zero or more conversion
69 modifiers, and exactly one conversion specifier.
73 Some modifiers exhibit the same behaviour for all specifiers, other modifiers
74 indicate different behaviours for different specifiers, and other modifiers
75 are only applicable to certain specifiers. The relationship is described for
76 each modifier. The number 9 is used to denotes an arbitrary integer.
78 @em Positional ( @c 9$ ) [UNIX98]
80 Normally the arguments supplied to these functions are interpreted
81 incrementially from left to right. Arguments can be referenced specifically in
82 the format string. The modifier n$ selects the nth argument. The first
83 argument is referred as 1$. If this modifier is used, it must be the first
84 modifier after the indication character. n$ can also be used for argument
85 width, precision, and base.
87 The performance penalty of using positionals is almost neglible (contrary to
88 most other printf implementations).
90 @li @em Reference @em Mix.
91 Mixing normal and positional specifiers is allowed [TRIO]. For example,
93 trio_printf("%d %3$d %2$d\n", 1, 2, 3);
99 Arguments for the printf family are passed on the stack. On most platforms it
100 is not possible to determine the size of individual stack elements, so it is
101 essential that the format string corresponds exactly to the passed arguments.
102 If this is not the case, incorrect values may be put into the result.
104 @li @em Reference @em Gap.
105 For the same reason it is also essential that the format string does not
106 contain any "gaps" in the positional arguments. For example,
108 trio_printf("%1$d %3$d\n", 1, 2, 3);
110 is NOT allowed. The format string parser has no knowledge about whether the
111 second argument is, say, an integer or a long double (which have different
115 [UNIX98] describes this as unspecified behaviour. [TRIO] will detect reference
116 gaps and return an error.
118 @li @em Double @em Reference.
119 It is also not allowed to reference an argument twice or more. For example,
121 trio_printf("%1$d %1$lf\n", 1);
123 is NOT allowed, because it references the first argument as two differently
127 [UNIX98] describes this as unspecified behaviour. [TRIO] will detect double
128 references and return an error.
130 The following two statements are equivalent
132 trio_printf("|%d %s\n|", 42, "meanings");
135 trio_printf("|%1$d %2$s|\n", 42, "meanings");
141 Specifies the minimum width of a field. If the fields has less characters than
142 specified by the width, the field will be left adjusted and padded by spaces.
143 The adjustment and padding can be changed by the Alignment ( @c - ) and
144 Padding ( @c 0 ) modifiers.
146 The width is specified as a number. If an asterix ( @c * ) is used instead, the
147 width will be read from the argument list.
149 Prefixes, such as 0x for hexadecimal integers, are part of width.
151 trio_printf("|%10i|\n", 42);
155 @em Precision ( @c .9 )
157 The precision has different semantics for the various data types.
158 The precision specifies the maximum number of printed characters for strings,
159 the number of digits after the decimal-point for floating-point numbers,
160 the number of significant digits for the @c g (and @c G) representation of
161 floating-point numbers, the minimum number of printed digits for integers.
163 trio_printf("|%10.8i|%.8i|\n", 42, 42);
167 @em Base ( @c ..9 ) [TRIO]
169 Sets the base that the associated integer must be converted to. The base can
170 be between 2 and 36 (both included).
172 trio_printf("|%10.8.2i|%10..2i|%..2i|\n", 42, 42, 42);
173 | 00101010| 101010|101010|
175 trio_printf("|%*.8.*i|\n", 10, 2, 42);
181 Integer and floating point numbers are prepended by zeros. The number of
182 leading zeros are determined by the precision. If precision is not present,
183 width is used instead.
187 Integer arguments are read as an ( @c unsigned ) @c short @c int. String
188 and character arguments are read as @c char @c * and @c char respectively.
190 @em Short @em short ( @c hh ) [C99, GNU]
192 The argument is read as an ( @c unsigned ) @c char.
194 @em Fixed @em Size ( @c I ) [MSVC]
196 The argument is read as a fixed sized integer. The modifier is followed by
197 a number, which specifies the number of bits in the integer, and can be one
203 @li @c I64 (if 64-bits integers are supported)
205 Works only for integers (i, u, d, o, x, X)
207 @em Largest ( @c j ) [C99]
209 The argument is read as an @c intmax_t / @c uintmax_t, which is defined to
210 be the largest signed/unsigned integer.
214 An integral argument is read as an ( @c unsigned ) @c long @c int. A string
215 argument is read as a @c wchar_t @c *, and output as a multi-byte character
218 @em Long @em long ( @c ll ) [C99, UNIX98, GNU]
220 The argument is read as an ( @c unsigned ) @c long @c long @c int.
222 @em Long @em double ( @c L ) [C99, UNIX98, GNU]
224 The argument is read as a @c long @c double.
226 @em ptrdiff_t ( @c t ) [C99]
228 The argument is read as a @c ptrdiff_t, which is defined to be the signed
229 integer type of the result of subtracting two pointers.
231 @em Quad ( @c q ) [BSD, GNU]
233 Corresponds to the long long modifier ( @c ll ).
235 @em Wide ( @c w ) [MISC]
237 For a string argument this is equivalent to using the long modifier ( @c l ).
239 @em size_t ( @c z ) [C99]
241 The argument is read as a @c size_t, which is defined to be the type
242 returned by the @c sizeof operator.
244 @em size_t ( @c Z ) [GNU]
246 Corresponds to the size_t modifier ( @c z ).
248 @em Alternative ( @c # )
250 Prepend radix indicator for hexadecimal, octal, and binary integer numbers
252 Always add a decimal-point for floating-point numbers.
253 Escape non-printable characters for strings.
257 Prepend leading spaces when necessary.
261 Always prepend a sign to numbers. Normally only the negative sign is prepended
262 to a number. With this modifier the positive sign may also be prepended.
264 @em Alignment ( @c - )
266 The output will be left-justified in the field specified by the width.
268 @em Argument ( @c * )
270 Width, precision, or base is read from the argument list, rather than from
271 the formatting string.
273 @em Quote / @em Grouping ( @c ' ) [MISC]
275 Groups integers and the integer-part of floating-point numbers according to
276 the locale. Quote strings and characters.
278 @em Sticky ( @c ! ) [TRIO]
280 The modifiers listed for the current specifier will be reused by subsequent
281 specifiers of the same group.
282 The following specifier groups exists
283 @li Integer ( @c i, @c u, @c d, @c o, @c x, @c X )
284 @li Floating-point ( @c f, @c F, @c e, @c E, @c g, @c G, @c a, @c A )
285 @li Character ( @c c )
292 The sticky modifiers are active until superseeded by other sticky modifiers,
293 or the end of the format string is reached.
294 Local modifiers overrides sticky modifiers for the given specifier only.
296 trio_printf("|%!08#x|%04x|%x|\n", 42, 42, 42);
297 |0x00002a|0x2a|0x00002a|
304 Produce a percent ( @c % ) character. This is used to quote the indication
305 character. No modifiers are allowed.
306 The full syntax is @c %%.
308 trio_printf("Percent is %%\n");
312 @em Hex @em floats ( @c a, @c A ) [C99]
314 Output a hexadecimal (base 16) representation of a floating point number. The
315 number is automatically preceeded by @c 0x ( or @c 0X ). The exponent is
318 trio_printf("|%a|%A|\n", 3.1415, 3.1415e20);
319 |0x3.228bc|0X3.228BCP+14|
322 @em Binary @em numbers ( @c b, @c B ) [MISC - SCO UnixWare 7]
324 DEPRECATED: Use Base modifier @c %..2i instead.
326 @em Character ( @c c )
328 Output a single character.
330 @li Quote ( @c ' ) [TRIO].
335 Output a decimal (base 10) representation of a number.
337 @li Grouping ( @c ' ) [TRIO].
338 The number is separated by the locale thousand separator.
340 trio_printf("|%'ld|\n", 1234567);
344 @em Floating-point ( @c e, @c E)
346 Output a decimal floating-point number.
347 The style is @c [-]9.99e[-]9, where
348 @li @c [-]9.99 is the mantissa (as described for the @c f, @c F specifier), and
349 @li @c e[-]9 is the exponent indicator (either @c e or @c E, depending on the
350 floating-point specifier), followed by an optional sign and the exponent
352 If the precision is wider than the maximum number of digits that can be
353 represented by the floating-point unit, then the number will be adequately
354 rounded. For example, assuming DBL_DIG is 15
356 trio_printf("|%.18e|\n", (1.0 / 3.0));
357 |3.333333333333333000e-01|
360 @em Floating-point ( @c f, @c F )
362 Output a decimal floating-point number.
363 The style is @c [-]9.99, where
364 @li @c [-] is an optional sign (either @c + or @c -),
365 @li @c 9 is the integer-part (possibly interspersed with thousand-separators),
366 @li @c . is the decimal-point (depending on the locale), and
367 @li @c 99 is the fractional-part.
369 If more digits are needed to output the number, than can be represented with
370 the accuracy of the floating-point unit, then the number will be adequately
371 rounded. For example, assuming that DBL_DIG is 15
373 trio_printf("|%f|\n", (2.0 / 3.0) * 1E18);
374 |666666666666666700.000000|
377 The following modifiers holds a special meaning for this specifier
378 @li Alternative ( @c # ) [C99].
380 @li Grouping ( @c ' ) [TRIO].
381 Group integer part of number into thousands (according to locale).
383 @em Floating-point ( @c g, @c G)
385 Output a decimal floating-point representation of a number. The format of
386 either the @c f, @c F specifier or the @c e, @c E specifier is used, whatever
387 produces the shortest result.
391 Output a signed integer. Default base is 10.
393 @em Errno ( @c m ) [GNU]
397 Insert into the location pointed to by the argument, the number of octets
398 written to the output so far.
402 Output an octal (base 8) representation of a number.
406 Ouput the address of the argument. The address is printed as a hexadecimal
407 number. If the argument is the NULL pointer the text @c (nil) will be used
409 @li Alternative ( @c # ) [TRIO].
412 @em String ( @c s, @c S )
414 Output a string. The argument must point to a zero terminated string. If the
415 argument is the NULL pointer the text @c (nil) will be used instead.
416 @c S is equivalent to @c ls.
417 @li Alternative ( @c # ) [TRIO].
418 Escape non-printable characters.
420 Non-printable characters are converted into C escapes, or hexadecimal numbers
421 where no C escapes exists for the character. The C escapes, the hexadecimal
422 number, and all backslashes are prepended by a backslash ( @c \ ).
423 The supported C escapes are
424 @li @c \a (\007) = alert
425 @li @c \b (\010) = backspace
426 @li @c \f (\014) = formfeed
427 @li @c \n (\012) = newline
428 @li @c \r (\015) = carriage return
429 @li @c \t (\011) = horizontal tab
430 @li @c \v (\013) = vertical tab
433 trio_printf("|One %s Three|One %'s Three|\n", "Two", "Two");
434 |One Two Three|One "Two" Three|
436 trio_printf("|Argument missing %s|\n", NULL);
437 |Argument missing (nil)|
439 trio_printf("|%#s|\n", "\007 \a.");
443 @em Unsigned ( @c u )
445 Output an unsigned integer. Default base is 10.
447 @em Hex ( @c x, @c X )
449 Output a hexadecimal (base 16) representation of a number.
451 @li Alternative ( @c # ).
452 Preceed the number by @c 0x ( or @c 0X ). The two characters are counted
453 as part of the width.
455 @em User-defined ( @c <> )
457 Invoke user-defined formatting.
458 See @ref trio_register for further information.
462 All functions returns the number of outputted characters. If an error occured
463 then a negative error code is returned [TRIO]. Note that this is a deviation
464 from the standard, which simply returns -1 (or EOF) and errno set
466 The error condition can be detected by checking whether the function returns
467 a negative number or not, and the number can be parsed with the following
468 macros. The error codes are primarily intended as debugging aide for the
471 @li TRIO_EINVAL: Invalid argument.
472 @li TRIO_ETOOMANY: Too many arguments.
473 @li TRIO_EDBLREF: Double argument reference.
474 @li TRIO_EGAP: Argument reference gap.
475 @li TRIO_ENOMEM: Out of memory.
476 @li TRIO_ERANGE: Invalid range.
477 @li TRIO_ERRNO: The error is specified by the errno variable.
483 rc = trio_printf("%r\n", 42);
485 if (TRIO_ERROR_CODE(rc) != TRIO_EOF) {
486 trio_printf("Error: %s at position %d\n",
488 TRIO_ERROR_POSITION(rc));
495 @e trio_scanf, @e trio_register.
499 The printfv family uses an array rather than the stack to pass arguments.
500 This means that @c short @c int and @c float values will not be handled by
501 the default argument promotion in C. Instead, these values must be explicitly
502 converted with the Short (h) modifier in both cases.
507 float float_number = 42.0;
508 short short_number = 42;
510 array[0] = &float_number;
511 array[1] = &short_number;
513 trio_printfv("%hf %hd\n", array); /* CORRECT */
514 trio_printfv("%f %d\n", array); /* WRONG */
519 Throughout this document the following abbreviations have been used to
520 indicate what standard a feature conforms to. If nothing else is indicated
521 ANSI C (C89) is assumed.
523 @li [C89] ANSI X3.159-1989
524 @li [C99] ISO/IEC 9899:1999
525 @li [UNIX98] The Single UNIX Specification, Version 2
528 @li [MSVC] Microsoft Visual C
529 @li [MISC] Other non-standard sources
530 @li [TRIO] Extensions specific for this package