1 /************************************************************************* 2 * 3 * $Id$ 4 * 5 * Copyright (C) 2001 Bjorn Reese and Daniel Stenberg. 6 * 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. 10 * 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. 15 * 16 ************************************************************************/ 17 18 /** @addtogroup Printf Formatted Printing Functions. 19 Variations of formatted printing functions. 20 21 @b SYNOPSIS 22 23 @verbatim 24 cc ... -ltrio -lm 25 26 #include <trio.h> 27 @endverbatim 28 29 @b DESCRIPTION 30 31 This documentation is incomplete. 32 The documentation of the printf family in [C99] and [UNIX98] also applies 33 to the trio counterparts. 34 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. 38 39 @ref trio_printf, @ref trio_vprintf, and @ref trio_printfv writes the 40 output to the standard output stream (stdout). 41 42 @ref trio_fprintf, @ref trio_vfprintf, and @ref trio_fprintfv writes the 43 output to a given output stream. 44 45 @ref trio_dprintf, @ref trio_vdprintf, and @ref trio_dprintfv writes the 46 output to a file descriptor (this includes, for example, sockets). 47 48 @ref trio_sprintf, @ref trio_vsprintf, and @ref trio_sprintfv writes the 49 output into @p buffer. 50 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. 57 58 @ref trio_snprintfcat appends the formatted text at the end of @p buffer. 59 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. 62 63 @b FORMATTING 64 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. 70 71 @b Modifiers 72 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. 77 78 @em Positional ( @c 9$ ) [UNIX98] 79 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. 86 87 The performance penalty of using positionals is almost neglible (contrary to 88 most other printf implementations). 89 90 @li @em Reference @em Mix. 91 Mixing normal and positional specifiers is allowed [TRIO]. For example, 92 @verbatim 93 trio_printf("%d %3$d %2$d\n", 1, 2, 3); 94 @endverbatim 95 results in 96 @verbatim 97 1 3 2 98 @endverbatim 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. 103 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, 107 @verbatim 108 trio_printf("%1$d %3$d\n", 1, 2, 3); 109 @endverbatim 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 112 sizes). 113 @verbatim 114 @endverbatim 115 [UNIX98] describes this as unspecified behaviour. [TRIO] will detect reference 116 gaps and return an error. 117 118 @li @em Double @em Reference. 119 It is also not allowed to reference an argument twice or more. For example, 120 @verbatim 121 trio_printf("%1$d %1$lf\n", 1); 122 @endverbatim 123 is NOT allowed, because it references the first argument as two differently 124 sized objects. 125 @verbatim 126 @endverbatim 127 [UNIX98] describes this as unspecified behaviour. [TRIO] will detect double 128 references and return an error. 129 130 The following two statements are equivalent 131 @verbatim 132 trio_printf("|%d %s\n|", 42, "meanings"); 133 |42 meanings| 134 135 trio_printf("|%1$d %2$s|\n", 42, "meanings"); 136 |42 meanings| 137 @endverbatim 138 139 @em Width ( @c 9 ) 140 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. 145 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. 148 149 Prefixes, such as 0x for hexadecimal integers, are part of width. 150 @verbatim 151 trio_printf("|%10i|\n", 42); 152 | 42| 153 @endverbatim 154 155 @em Precision ( @c .9 ) 156 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. 162 @verbatim 163 trio_printf("|%10.8i|%.8i|\n", 42, 42); 164 | 00000042|00000042| 165 @endverbatim 166 167 @em Base ( @c ..9 ) [TRIO] 168 169 Sets the base that the associated integer must be converted to. The base can 170 be between 2 and 36 (both included). 171 @verbatim 172 trio_printf("|%10.8.2i|%10..2i|%..2i|\n", 42, 42, 42); 173 | 00101010| 101010|101010| 174 175 trio_printf("|%*.8.*i|\n", 10, 2, 42); 176 | 00101010| 177 @endverbatim 178 179 @em Padding ( @c 0 ) 180 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. 184 185 @em Short ( @c h ) 186 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. 189 190 @em Short @em short ( @c hh ) [C99, GNU] 191 192 The argument is read as an ( @c unsigned ) @c char. 193 194 @em Fixed @em Size ( @c I ) [MSVC] 195 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 198 of the following 199 200 @li @c I8 201 @li @c I16 202 @li @c I32 203 @li @c I64 (if 64-bits integers are supported) 204 205 Works only for integers (i, u, d, o, x, X) 206 207 @em Largest ( @c j ) [C99] 208 209 The argument is read as an @c intmax_t / @c uintmax_t, which is defined to 210 be the largest signed/unsigned integer. 211 212 @em Long ( @c l ) 213 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 216 sequence. 217 218 @em Long @em long ( @c ll ) [C99, UNIX98, GNU] 219 220 The argument is read as an ( @c unsigned ) @c long @c long @c int. 221 222 @em Long @em double ( @c L ) [C99, UNIX98, GNU] 223 224 The argument is read as a @c long @c double. 225 226 @em ptrdiff_t ( @c t ) [C99] 227 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. 230 231 @em Quad ( @c q ) [BSD, GNU] 232 233 Corresponds to the long long modifier ( @c ll ). 234 235 @em Wide ( @c w ) [MISC] 236 237 For a string argument this is equivalent to using the long modifier ( @c l ). 238 239 @em size_t ( @c z ) [C99] 240 241 The argument is read as a @c size_t, which is defined to be the type 242 returned by the @c sizeof operator. 243 244 @em size_t ( @c Z ) [GNU] 245 246 Corresponds to the size_t modifier ( @c z ). 247 248 @em Alternative ( @c # ) 249 250 Prepend radix indicator for hexadecimal, octal, and binary integer numbers 251 and for pointers. 252 Always add a decimal-point for floating-point numbers. 253 Escape non-printable characters for strings. 254 255 @em Spacing ( ) 256 257 Prepend leading spaces when necessary. 258 259 @em Sign ( @c + ) 260 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. 263 264 @em Alignment ( @c - ) 265 266 The output will be left-justified in the field specified by the width. 267 268 @em Argument ( @c * ) 269 270 Width, precision, or base is read from the argument list, rather than from 271 the formatting string. 272 273 @em Quote / @em Grouping ( @c ' ) [MISC] 274 275 Groups integers and the integer-part of floating-point numbers according to 276 the locale. Quote strings and characters. 277 278 @em Sticky ( @c ! ) [TRIO] 279 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 ) 286 @li String ( @c s ) 287 @li Pointer ( @c p ) 288 @li Count ( @c n ) 289 @li Errno ( @c m ) 290 @li Group ( @c [] ) 291 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. 295 @verbatim 296 trio_printf("|%!08#x|%04x|%x|\n", 42, 42, 42); 297 |0x00002a|0x2a|0x00002a| 298 @endverbatim 299 300 @b Specifiers 301 302 @em Percent ( @c % ) 303 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 %%. 307 @verbatim 308 trio_printf("Percent is %%\n"); 309 Percent is % 310 @endverbatim 311 312 @em Hex @em floats ( @c a, @c A ) [C99] 313 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 316 @c p ( or @c P ). 317 @verbatim 318 trio_printf("|%a|%A|\n", 3.1415, 3.1415e20); 319 |0x3.228bc|0X3.228BCP+14| 320 @endverbatim 321 322 @em Binary @em numbers ( @c b, @c B ) [MISC - SCO UnixWare 7] 323 324 DEPRECATED: Use Base modifier @c %..2i instead. 325 326 @em Character ( @c c ) 327 328 Output a single character. 329 330 @li Quote ( @c ' ) [TRIO]. 331 Quote the character. 332 333 @em Decimal ( @c d ) 334 335 Output a decimal (base 10) representation of a number. 336 337 @li Grouping ( @c ' ) [TRIO]. 338 The number is separated by the locale thousand separator. 339 @verbatim 340 trio_printf("|%'ld|\n", 1234567); 341 |1,234,567| 342 @endverbatim 343 344 @em Floating-point ( @c e, @c E) 345 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 351 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 355 @verbatim 356 trio_printf("|%.18e|\n", (1.0 / 3.0)); 357 |3.333333333333333000e-01| 358 @endverbatim 359 360 @em Floating-point ( @c f, @c F ) 361 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. 368 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 372 @verbatim 373 trio_printf("|%f|\n", (2.0 / 3.0) * 1E18); 374 |666666666666666700.000000| 375 @endverbatim 376 377 The following modifiers holds a special meaning for this specifier 378 @li Alternative ( @c # ) [C99]. 379 Add decimal point. 380 @li Grouping ( @c ' ) [TRIO]. 381 Group integer part of number into thousands (according to locale). 382 383 @em Floating-point ( @c g, @c G) 384 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. 388 389 @em Integer ( @c i ) 390 391 Output a signed integer. Default base is 10. 392 393 @em Errno ( @c m ) [GNU] 394 395 @em Count ( @c n ) 396 397 Insert into the location pointed to by the argument, the number of octets 398 written to the output so far. 399 400 @em Octal ( @c o ) 401 402 Output an octal (base 8) representation of a number. 403 404 @em Pointer ( @c p ) 405 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 408 instead. 409 @li Alternative ( @c # ) [TRIO]. 410 Prepend 0x 411 412 @em String ( @c s, @c S ) 413 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. 419 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 431 432 @verbatim 433 trio_printf("|One %s Three|One %'s Three|\n", "Two", "Two"); 434 |One Two Three|One "Two" Three| 435 436 trio_printf("|Argument missing %s|\n", NULL); 437 |Argument missing (nil)| 438 439 trio_printf("|%#s|\n", "\007 \a."); 440 |\a \a.| 441 @endverbatim 442 443 @em Unsigned ( @c u ) 444 445 Output an unsigned integer. Default base is 10. 446 447 @em Hex ( @c x, @c X ) 448 449 Output a hexadecimal (base 16) representation of a number. 450 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. 454 455 @em User-defined ( @c <> ) 456 457 Invoke user-defined formatting. 458 See @ref trio_register for further information. 459 460 @b RETURN @b VALUES 461 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 465 appropriately. 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 469 developer. 470 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. 478 479 Example: 480 @verbatim 481 int rc; 482 483 rc = trio_printf("%r\n", 42); 484 if (rc < 0) { 485 if (TRIO_ERROR_CODE(rc) != TRIO_EOF) { 486 trio_printf("Error: %s at position %d\n", 487 TRIO_ERROR_NAME(rc), 488 TRIO_ERROR_POSITION(rc)); 489 } 490 } 491 @endverbatim 492 493 @b SEE @b ALSO 494 495 @e trio_scanf, @e trio_register. 496 497 @b NOTES 498 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. 503 504 Example: 505 @verbatim 506 void *array[2]; 507 float float_number = 42.0; 508 short short_number = 42; 509 510 array[0] = &float_number; 511 array[1] = &short_number; 512 513 trio_printfv("%hf %hd\n", array); /* CORRECT */ 514 trio_printfv("%f %d\n", array); /* WRONG */ 515 @endverbatim 516 517 @b CONFORMING @b TO 518 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. 522 523 @li [C89] ANSI X3.159-1989 524 @li [C99] ISO/IEC 9899:1999 525 @li [UNIX98] The Single UNIX Specification, Version 2 526 @li [BSD] 4.4BSD 527 @li [GNU] GNU libc 528 @li [MSVC] Microsoft Visual C 529 @li [MISC] Other non-standard sources 530 @li [TRIO] Extensions specific for this package 531 532 */ 533