1<html lang="en"> 2<head> 3<title>swprintf - Untitled</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Untitled"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Stdio.html#Stdio" title="Stdio"> 9<link rel="prev" href="sscanf.html#sscanf" title="sscanf"> 10<link rel="next" href="swscanf.html#swscanf" title="swscanf"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<meta http-equiv="Content-Style-Type" content="text/css"> 13<style type="text/css"><!-- 14 pre.display { font-family:inherit } 15 pre.format { font-family:inherit } 16 pre.smalldisplay { font-family:inherit; font-size:smaller } 17 pre.smallformat { font-family:inherit; font-size:smaller } 18 pre.smallexample { font-size:smaller } 19 pre.smalllisp { font-size:smaller } 20 span.sc { font-variant:small-caps } 21 span.roman { font-family:serif; font-weight:normal; } 22 span.sansserif { font-family:sans-serif; font-weight:normal; } 23--></style> 24<link rel="stylesheet" type="text/css" href="../cs.css"> 25</head> 26<body> 27<div class="node"> 28<a name="swprintf"></a> 29<p> 30Next: <a rel="next" accesskey="n" href="swscanf.html#swscanf">swscanf</a>, 31Previous: <a rel="previous" accesskey="p" href="sscanf.html#sscanf">sscanf</a>, 32Up: <a rel="up" accesskey="u" href="Stdio.html#Stdio">Stdio</a> 33<hr> 34</div> 35 36<h3 class="section">4.62 <code>swprintf</code>, <code>fwprintf</code>, <code>wprintf</code>—wide character format output</h3> 37 38<p><a name="index-fwprintf-303"></a><a name="index-g_t_005ffwprintf_005fr-304"></a><a name="index-wprintf-305"></a><a name="index-g_t_005fwprintf_005fr-306"></a><a name="index-swprintf-307"></a><a name="index-g_t_005fswprintf_005fr-308"></a><strong>Synopsis</strong> 39<pre class="example"> #include <wchar.h> 40 41 int wprintf(const wchar_t *<var>format</var>, ...); 42 int fwprintf(FILE *<var>fd</var>, const wchar_t *<var>format</var>, ...); 43 int swprintf(wchar_t *<var>str</var>, size_t <var>size</var>, 44 const wchar_t *<var>format</var>, ...); 45 46 int _wprintf_r(struct _reent *<var>ptr</var>, const wchar_t *<var>format</var>, ...); 47 int _fwprintf_r(struct _reent *<var>ptr</var>, FILE *<var>fd</var>, 48 const wchar_t *<var>format</var>, ...); 49 int _swprintf_r(struct _reent *<var>ptr</var>, wchar_t *<var>str</var>, 50 size_t <var>size</var>, const wchar_t *<var>format</var>, ...); 51 52</pre> 53 <p><strong>Description</strong><br> 54<code>wprintf</code> accepts a series of arguments, applies to each a 55format specifier from <code>*</code><var>format</var>, and writes the 56formatted data to <code>stdout</code>, without a terminating NUL 57wide character. The behavior of <code>wprintf</code> is undefined if there 58are not enough arguments for the format or if any argument is not the 59right type for the corresponding conversion specifier. <code>wprintf</code> 60returns when it reaches the end of the format string. If there are 61more arguments than the format requires, excess arguments are 62ignored. 63 64 <p><code>fwprintf</code> is like <code>wprintf</code>, except that output is directed 65to the stream <var>fd</var> rather than <code>stdout</code>. 66 67 <p><code>swprintf</code> is like <code>wprintf</code>, except that output is directed 68to the buffer <var>str</var> with a terminating wide <code>NUL</code>, and the 69resulting string length is limited to at most <var>size</var> wide characters, 70including the terminating <code>NUL</code>. It is considered an error if the 71output (including the terminating wide-<code>NULL</code>) does not fit into 72<var>size</var> wide characters. (This error behavior is not the same as for 73<code>snprintf</code>, which <code>swprintf</code> is otherwise completely analogous to. 74While <code>snprintf</code> allows the needed size to be known simply by giving 75<var>size</var>=0, <code>swprintf</code> does not, giving an error instead.) 76 77 <p>For <code>swprintf</code> the behavior is undefined if the output 78<code>*</code><var>str</var> overlaps with one of the arguments. Behavior is also 79undefined if the argument for <code>%n</code> within <code>*</code><var>format</var> 80overlaps another argument. 81 82 <p><var>format</var> is a pointer to a wide character string containing two 83types of objects: ordinary characters (other than <code>%</code>), 84which are copied unchanged to the output, and conversion 85specifications, each of which is introduced by <code>%</code>. (To 86include <code>%</code> in the output, use <code>%%</code> in the format string.) 87A conversion specification has the following form: 88 89<pre class="smallexample"> %[<var>pos</var>][<var>flags</var>][<var>width</var>][.<var>prec</var>][<var>size</var>]<var>type</var> 90</pre> 91 <p>The fields of the conversion specification have the following 92meanings: 93 94 <ul> 95<li><var>pos</var> 96 97 <p>Conversions normally consume arguments in the order that they 98are presented. However, it is possible to consume arguments 99out of order, and reuse an argument for more than one 100conversion specification (although the behavior is undefined 101if the same argument is requested with different types), by 102specifying <var>pos</var>, which is a decimal integer followed by 103'$'. The integer must be between 1 and <NL_ARGMAX> from 104limits.h, and if argument <code>%n$</code> is requested, all earlier 105arguments must be requested somewhere within <var>format</var>. If 106positional parameters are used, then all conversion 107specifications except for <code>%%</code> must specify a position. 108This positional parameters method is a POSIX extension to the C 109standard definition for the functions. 110 111 <li><var>flags</var> 112 113 <p><var>flags</var> is an optional sequence of characters which control 114output justification, numeric signs, decimal points, trailing 115zeros, and octal and hex prefixes. The flag characters are 116minus (<code>-</code>), plus (<code>+</code>), space ( ), zero (<code>0</code>), sharp 117(<code>#</code>), and quote (<code>'</code>). They can appear in any 118combination, although not all flags can be used for all 119conversion specification types. 120 121 <dl> 122<dt><code>'</code><dd>A POSIX extension to the C standard. However, this 123implementation presently treats it as a no-op, which 124is the default behavior for the C locale, anyway. (If 125it did what it is supposed to, when <var>type</var> were <code>i</code>, 126<code>d</code>, <code>u</code>, <code>f</code>, <code>F</code>, <code>g</code>, or <code>G</code>, the 127integer portion of the conversion would be formatted 128with thousands' grouping wide characters.) 129 130 <br><dt><code>-</code><dd>The result of the conversion is left 131justified, and the right is padded with 132blanks. If you do not use this flag, the 133result is right justified, and padded on the 134left. 135 136 <br><dt><code>+</code><dd>The result of a signed conversion (as 137determined by <var>type</var> of <code>d</code>, <code>i</code>, <code>a</code>, 138<code>A</code>, <code>e</code>, <code>E</code>, <code>f</code>, <code>F</code>, <code>g</code>, or 139<code>G</code>) will always begin with a plus or minus 140sign. (If you do not use this flag, positive 141values do not begin with a plus sign.) 142 143 <br><dt><code>" " (space)</code><dd>If the first character of a signed conversion 144specification is not a sign, or if a signed 145conversion results in no characters, the 146result will begin with a space. If the space 147( ) flag and the plus (<code>+</code>) flag both 148appear, the space flag is ignored. 149 150 <br><dt><code>0</code><dd>If the <var>type</var> character is <code>d</code>, <code>i</code>, 151<code>o</code>, <code>u</code>, <code>x</code>, <code>X</code>, <code>a</code>, <code>A</code>, 152<code>e</code>, <code>E</code>, <code>f</code>, <code>F</code>, <code>g</code>, or <code>G</code>: leading 153zeros are used to pad the field width 154(following any indication of sign or base); no 155spaces are used for padding. If the zero 156(<code>0</code>) and minus (<code>-</code>) flags both appear, 157the zero (<code>0</code>) flag will be ignored. For 158<code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, and <code>X</code> 159conversions, if a precision <var>prec</var> is 160specified, the zero (<code>0</code>) flag is ignored. 161 162 <p>Note that <code>0</code> is interpreted as a flag, not 163as the beginning of a field width. 164 165 <br><dt><code>#</code><dd>The result is to be converted to an 166alternative form, according to the <var>type</var> 167character: 168 169 <dl> 170<dt><code>o</code><dd>Increases precision to force the first 171digit of the result to be a zero. 172 173 <br><dt><code>x</code><dd>A non-zero result will have a <code>0x</code> 174prefix. 175 176 <br><dt><code>X</code><dd>A non-zero result will have a <code>0X</code> 177prefix. 178 179 <br><dt><code>a, A, e, E, f, or F</code><dd>The result will always contain a 180decimal point even if no digits follow 181the point. (Normally, a decimal point 182appears only if a digit follows it.) 183Trailing zeros are removed. 184 185 <br><dt><code>g or G</code><dd>The result will always contain a 186decimal point even if no digits follow 187the point. Trailing zeros are not 188removed. 189 190 <br><dt><code>all others</code><dd>Undefined. 191 192 </dl> 193 194 </dl> 195 196 <li><var>width</var> 197 198 <p><var>width</var> is an optional minimum field width. You can 199either specify it directly as a decimal integer, or 200indirectly by using instead an asterisk (<code>*</code>), in 201which case an <code>int</code> argument is used as the field 202width. If positional arguments are used, then the 203width must also be specified positionally as <code>*m$</code>, 204with m as a decimal integer. Negative field widths 205are treated as specifying the minus (<code>-</code>) flag for 206left justfication, along with a positive field width. 207The resulting format may be wider than the specified 208width. 209 210 <li><var>prec</var> 211 212 <p><var>prec</var> is an optional field; if present, it is 213introduced with `<code>.</code>' (a period). You can specify 214the precision either directly as a decimal integer or 215indirectly by using an asterisk (<code>*</code>), in which case 216an <code>int</code> argument is used as the precision. If 217positional arguments are used, then the precision must 218also be specified positionally as <code>*m$</code>, with m as a 219decimal integer. Supplying a negative precision is 220equivalent to omitting the precision. If only a 221period is specified the precision is zero. The effect 222depends on the conversion <var>type</var>. 223 224 <dl> 225<dt><code>d, i, o, u, x, or X</code><dd>Minimum number of digits to appear. If no 226precision is given, defaults to 1. 227 228 <br><dt><code>a or A</code><dd>Number of digits to appear after the decimal 229point. If no precision is given, the 230precision defaults to the minimum needed for 231an exact representation. 232 233 <br><dt><code>e, E, f or F</code><dd>Number of digits to appear after the decimal 234point. If no precision is given, the 235precision defaults to 6. 236 237 <br><dt><code>g or G</code><dd>Maximum number of significant digits. A 238precision of 0 is treated the same as a 239precision of 1. If no precision is given, the 240precision defaults to 6. 241 242 <br><dt><code>s or S</code><dd>Maximum number of characters to print from the 243string. If no precision is given, the entire 244string is printed. 245 246 <br><dt><code>all others</code><dd>undefined. 247 248 </dl> 249 250 <li><var>size</var> 251 252 <p><var>size</var> is an optional modifier that changes the data 253type that the corresponding argument has. Behavior is 254unspecified if a size is given that does not match the 255<var>type</var>. 256 257 <dl> 258<dt><code>hh</code><dd>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or 259<code>X</code>, specifies that the argument should be 260converted to a <code>signed char</code> or <code>unsigned 261char</code> before printing. 262 263 <p>With <code>n</code>, specifies that the argument is a 264pointer to a <code>signed char</code>. 265 266 <br><dt><code>h</code><dd>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or 267<code>X</code>, specifies that the argument should be 268converted to a <code>short</code> or <code>unsigned short</code> 269before printing. 270 271 <p>With <code>n</code>, specifies that the argument is a 272pointer to a <code>short</code>. 273 274 <br><dt><code>l</code><dd>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or 275<code>X</code>, specifies that the argument is a 276<code>long</code> or <code>unsigned long</code>. 277 278 <p>With <code>c</code>, specifies that the argument has 279type <code>wint_t</code>. 280 281 <p>With <code>s</code>, specifies that the argument is a 282pointer to <code>wchar_t</code>. 283 284 <p>With <code>n</code>, specifies that the argument is a 285pointer to a <code>long</code>. 286 287 <p>With <code>a</code>, <code>A</code>, <code>e</code>, <code>E</code>, <code>f</code>, <code>F</code>, 288<code>g</code>, or <code>G</code>, has no effect (because of 289vararg promotion rules, there is no need to 290distinguish between <code>float</code> and <code>double</code>). 291 292 <br><dt><code>ll</code><dd>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or 293<code>X</code>, specifies that the argument is a 294<code>long long</code> or <code>unsigned long long</code>. 295 296 <p>With <code>n</code>, specifies that the argument is a 297pointer to a <code>long long</code>. 298 299 <br><dt><code>j</code><dd>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or 300<code>X</code>, specifies that the argument is an 301<code>intmax_t</code> or <code>uintmax_t</code>. 302 303 <p>With <code>n</code>, specifies that the argument is a 304pointer to an <code>intmax_t</code>. 305 306 <br><dt><code>z</code><dd>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or 307<code>X</code>, specifies that the argument is a <code>size_t</code>. 308 309 <p>With <code>n</code>, specifies that the argument is a 310pointer to a <code>size_t</code>. 311 312 <br><dt><code>t</code><dd>With <code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>, or 313<code>X</code>, specifies that the argument is a 314<code>ptrdiff_t</code>. 315 316 <p>With <code>n</code>, specifies that the argument is a 317pointer to a <code>ptrdiff_t</code>. 318 319 <br><dt><code>L</code><dd>With <code>a</code>, <code>A</code>, <code>e</code>, <code>E</code>, <code>f</code>, <code>F</code>, 320<code>g</code>, or <code>G</code>, specifies that the argument 321is a <code>long double</code>. 322 323 </dl> 324 325 <li><var>type</var> 326 327 <p><var>type</var> specifies what kind of conversion <code>wprintf</code> 328performs. Here is a table of these: 329 330 <dl> 331<dt><code>%</code><dd>Prints the percent character (<code>%</code>). 332 333 <br><dt><code>c</code><dd>If no <code>l</code> qualifier is present, the int argument shall 334be converted to a wide character as if by calling 335the btowc() function and the resulting wide character 336shall be written. Otherwise, the wint_t argument 337shall be converted to wchar_t, and written. 338 339 <br><dt><code>C</code><dd>Short for <code>%lc</code>. A POSIX extension to the C standard. 340 341 <br><dt><code>s</code><dd>If no <code>l</code> qualifier is present, the application 342shall ensure that the argument is a pointer to a 343character array containing a character sequence 344beginning in the initial shift state. Characters 345from the array shall be converted as if by repeated 346calls to the mbrtowc() function, with the conversion 347state described by an mbstate_t object initialized to 348zero before the first character is converted, and 349written up to (but not including) the terminating 350null wide character. If the precision is specified, 351no more than that many wide characters shall be 352written. If the precision is not specified, or is 353greater than the size of the array, the application 354shall ensure that the array contains a null wide 355character. 356 357 <p>If an <code>l</code> qualifier is present, the application 358shall ensure that the argument is a pointer to an 359array of type wchar_t. Wide characters from the array 360shall be written up to (but not including) a 361terminating null wide character. If no precision is 362specified, or is greater than the size of the array, 363the application shall ensure that the array contains 364a null wide character. If a precision is specified, 365no more than that many wide characters shall be 366written. 367 368 <br><dt><code>S</code><dd>Short for <code>%ls</code>. A POSIX extension to the C standard. 369 370 <br><dt><code>d or i</code><dd>Prints a signed decimal integer; takes an 371<code>int</code>. Leading zeros are inserted as 372necessary to reach the precision. A value of 0 with 373a precision of 0 produces an empty string. 374 375 <br><dt><code>o</code><dd>Prints an unsigned octal integer; takes an 376<code>unsigned</code>. Leading zeros are inserted as 377necessary to reach the precision. A value of 0 with 378a precision of 0 produces an empty string. 379 380 <br><dt><code>u</code><dd>Prints an unsigned decimal integer; takes an 381<code>unsigned</code>. Leading zeros are inserted as 382necessary to reach the precision. A value of 0 with 383a precision of 0 produces an empty string. 384 385 <br><dt><code>x</code><dd>Prints an unsigned hexadecimal integer (using 386<code>abcdef</code> as digits beyond <code>9</code>); takes an 387<code>unsigned</code>. Leading zeros are inserted as 388necessary to reach the precision. A value of 0 with 389a precision of 0 produces an empty string. 390 391 <br><dt><code>X</code><dd>Like <code>x</code>, but uses <code>ABCDEF</code> as digits 392beyond <code>9</code>. 393 394 <br><dt><code>f</code><dd>Prints a signed value of the form 395<code>[-]9999.9999</code>, with the precision 396determining how many digits follow the decimal 397point; takes a <code>double</code> (remember that 398<code>float</code> promotes to <code>double</code> as a vararg). 399The low order digit is rounded to even. If 400the precision results in at most DECIMAL_DIG 401digits, the result is rounded correctly; if 402more than DECIMAL_DIG digits are printed, the 403result is only guaranteed to round back to the 404original value. 405 406 <p>If the value is infinite, the result is 407<code>inf</code>, and no zero padding is performed. If 408the value is not a number, the result is 409<code>nan</code>, and no zero padding is performed. 410 411 <br><dt><code>F</code><dd>Like <code>f</code>, but uses <code>INF</code> and <code>NAN</code> for 412non-finite numbers. 413 414 <br><dt><code>e</code><dd>Prints a signed value of the form 415<code>[-]9.9999e[+|-]999</code>; takes a <code>double</code>. 416The digit before the decimal point is non-zero 417if the value is non-zero. The precision 418determines how many digits appear between 419<code>.</code> and <code>e</code>, and the exponent always 420contains at least two digits. The value zero 421has an exponent of zero. If the value is not 422finite, it is printed like <code>f</code>. 423 424 <br><dt><code>E</code><dd>Like <code>e</code>, but using <code>E</code> to introduce the 425exponent, and like <code>F</code> for non-finite 426values. 427 428 <br><dt><code>g</code><dd>Prints a signed value in either <code>f</code> or <code>e</code> 429form, based on the given value and 430precision—an exponent less than -4 or 431greater than the precision selects the <code>e</code> 432form. Trailing zeros and the decimal point 433are printed only if necessary; takes a 434<code>double</code>. 435 436 <br><dt><code>G</code><dd>Like <code>g</code>, except use <code>F</code> or <code>E</code> form. 437 438 <br><dt><code>a</code><dd>Prints a signed value of the form 439<code>[-]0x1.ffffp[+|-]9</code>; takes a <code>double</code>. 440The letters <code>abcdef</code> are used for digits 441beyond <code>9</code>. The precision determines how 442many digits appear after the decimal point. 443The exponent contains at least one digit, and 444is a decimal value representing the power of 4452; a value of 0 has an exponent of 0. 446Non-finite values are printed like <code>f</code>. 447 448 <br><dt><code>A</code><dd>Like <code>a</code>, except uses <code>X</code>, <code>P</code>, and 449<code>ABCDEF</code> instead of lower case. 450 451 <br><dt><code>n</code><dd>Takes a pointer to <code>int</code>, and stores a count 452of the number of bytes written so far. No 453output is created. 454 455 <br><dt><code>p</code><dd>Takes a pointer to <code>void</code>, and prints it in 456an implementation-defined format. This 457implementation is similar to <code>%#tx</code>), except 458that <code>0x</code> appears even for the NULL pointer. 459 460 <br><dt><code>m</code><dd>Prints the output of <code>strerror(errno)</code>; no 461argument is required. A GNU extension. 462 463 </dl> 464 465 </ul> 466 467 <p><code>_wprintf_r</code>, <code>_fwprintf_r</code>, <code>_swprintf_r</code>, are simply 468reentrant versions of the functions above. 469 470 <p><br> 471<strong>Returns</strong><br> 472On success, <code>swprintf</code> return the number of wide characters in 473the output string, except the concluding <code>NUL</code> is not counted. 474<code>wprintf</code> and <code>fwprintf</code> return the number of characters transmitted. 475 476 <p>If an error occurs, the result of <code>wprintf</code>, <code>fwprintf</code>, and 477<code>swprintf</code> is a negative value. For <code>wprintf</code> and <code>fwprintf</code>, 478<code>errno</code> may be set according to <code>fputwc</code>. For <code>swprintf</code>, <code>errno</code> 479may be set to EOVERFLOW if <var>size</var> is greater than INT_MAX / sizeof (wchar_t), 480or when the output does not fit into <var>size</var> wide characters (including the 481terminating wide <code>NULL</code>). 482 483 <p><br> 484<strong>Bugs</strong><br> 485The “”' (quote) flag does not work when locale's thousands_sep is not empty. 486 487 <p><br> 488<strong>Portability</strong><br> 489POSIX-1.2008 with extensions; C99 (compliant except for POSIX extensions). 490 491 <p>Depending on how newlib was configured, not all format specifiers are 492supported. 493 494 <p>Supporting OS subroutines required: <code>close</code>, <code>fstat</code>, <code>isatty</code>, 495<code>lseek</code>, <code>read</code>, <code>sbrk</code>, <code>write</code>. 496 497 <p><br> 498 499 </body></html> 500 501