1*2fe8fb19SBen Gras.\" $NetBSD: wprintf.3,v 1.8 2010/12/16 17:42:27 wiz Exp $ 2*2fe8fb19SBen Gras.\" Copyright (c) 1990, 1991, 1993 3*2fe8fb19SBen Gras.\" The Regents of the University of California. All rights reserved. 4*2fe8fb19SBen Gras.\" 5*2fe8fb19SBen Gras.\" This code is derived from software contributed to Berkeley by 6*2fe8fb19SBen Gras.\" Chris Torek and the American National Standards Committee X3, 7*2fe8fb19SBen Gras.\" on Information Processing Systems. 8*2fe8fb19SBen Gras.\" 9*2fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without 10*2fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions 11*2fe8fb19SBen Gras.\" are met: 12*2fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright 13*2fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer. 14*2fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright 15*2fe8fb19SBen Gras.\" notice, this list of conditions and the following disclaimer in the 16*2fe8fb19SBen Gras.\" documentation and/or other materials provided with the distribution. 17*2fe8fb19SBen Gras.\" 3. All advertising materials mentioning features or use of this software 18*2fe8fb19SBen Gras.\" must display the following acknowledgement: 19*2fe8fb19SBen Gras.\" This product includes software developed by the University of 20*2fe8fb19SBen Gras.\" California, Berkeley and its contributors. 21*2fe8fb19SBen Gras.\" 4. Neither the name of the University nor the names of its contributors 22*2fe8fb19SBen Gras.\" may be used to endorse or promote products derived from this software 23*2fe8fb19SBen Gras.\" without specific prior written permission. 24*2fe8fb19SBen Gras.\" 25*2fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 26*2fe8fb19SBen Gras.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27*2fe8fb19SBen Gras.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28*2fe8fb19SBen Gras.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 29*2fe8fb19SBen Gras.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30*2fe8fb19SBen Gras.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31*2fe8fb19SBen Gras.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32*2fe8fb19SBen Gras.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33*2fe8fb19SBen Gras.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34*2fe8fb19SBen Gras.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35*2fe8fb19SBen Gras.\" SUCH DAMAGE. 36*2fe8fb19SBen Gras.\" 37*2fe8fb19SBen Gras.\" @(#)printf.3 8.1 (Berkeley) 6/4/93 38*2fe8fb19SBen Gras.\" FreeBSD: src/lib/libc/stdio/printf.3,v 1.47 2002/09/06 11:23:55 tjr Exp 39*2fe8fb19SBen Gras.\" $FreeBSD: src/lib/libc/stdio/wprintf.3,v 1.5 2003/07/05 07:55:34 tjr Exp $ 40*2fe8fb19SBen Gras.\" 41*2fe8fb19SBen Gras.Dd April 30, 2010 42*2fe8fb19SBen Gras.Dt WPRINTF 3 43*2fe8fb19SBen Gras.Os 44*2fe8fb19SBen Gras.Sh NAME 45*2fe8fb19SBen Gras.Nm wprintf , fwprintf , swprintf , 46*2fe8fb19SBen Gras.Nm vwprintf , vfwprintf , vswprintf 47*2fe8fb19SBen Gras.Nd formatted wide character output conversion 48*2fe8fb19SBen Gras.Sh LIBRARY 49*2fe8fb19SBen Gras.Lb libc 50*2fe8fb19SBen Gras.Sh SYNOPSIS 51*2fe8fb19SBen Gras.In stdio.h 52*2fe8fb19SBen Gras.In wchar.h 53*2fe8fb19SBen Gras.Ft int 54*2fe8fb19SBen Gras.Fn fwprintf "FILE * restrict stream" "const wchar_t * restrict format" ... 55*2fe8fb19SBen Gras.Ft int 56*2fe8fb19SBen Gras.Fn swprintf "wchar_t * restrict ws" "size_t n" "const wchar_t * restrict format" ... 57*2fe8fb19SBen Gras.Ft int 58*2fe8fb19SBen Gras.Fn wprintf "const wchar_t * restrict format" ... 59*2fe8fb19SBen Gras.In stdarg.h 60*2fe8fb19SBen Gras.Ft int 61*2fe8fb19SBen Gras.Fn vfwprintf "FILE * restrict stream" "const wchar_t * restrict" "va_list ap" 62*2fe8fb19SBen Gras.Ft int 63*2fe8fb19SBen Gras.Fn vswprintf "wchar_t * restrict ws" "size_t n" "const wchar_t *restrict format" "va_list ap" 64*2fe8fb19SBen Gras.Ft int 65*2fe8fb19SBen Gras.Fn vwprintf "const wchar_t * restrict format" "va_list ap" 66*2fe8fb19SBen Gras.Sh DESCRIPTION 67*2fe8fb19SBen GrasThe 68*2fe8fb19SBen Gras.Fn wprintf 69*2fe8fb19SBen Grasfamily of functions produces output according to a 70*2fe8fb19SBen Gras.Fa format 71*2fe8fb19SBen Grasas described below. 72*2fe8fb19SBen GrasThe 73*2fe8fb19SBen Gras.Fn wprintf 74*2fe8fb19SBen Grasand 75*2fe8fb19SBen Gras.Fn vwprintf 76*2fe8fb19SBen Grasfunctions 77*2fe8fb19SBen Graswrite output to 78*2fe8fb19SBen Gras.Dv stdout , 79*2fe8fb19SBen Grasthe standard output stream; 80*2fe8fb19SBen Gras.Fn fwprintf 81*2fe8fb19SBen Grasand 82*2fe8fb19SBen Gras.Fn vfwprintf 83*2fe8fb19SBen Graswrite output to the given output 84*2fe8fb19SBen Gras.Fa stream ; 85*2fe8fb19SBen Gras.Fn swprintf 86*2fe8fb19SBen Grasand 87*2fe8fb19SBen Gras.Fn vswprintf 88*2fe8fb19SBen Graswrite to the wide-character string 89*2fe8fb19SBen Gras.Fa ws . 90*2fe8fb19SBen Gras.Pp 91*2fe8fb19SBen GrasThese functions write the output under the control of a 92*2fe8fb19SBen Gras.Fa format 93*2fe8fb19SBen Grasstring that specifies how subsequent arguments 94*2fe8fb19SBen Gras(or arguments accessed via the variable-length argument facilities of 95*2fe8fb19SBen Gras.Xr stdarg 3 ) 96*2fe8fb19SBen Grasare converted for output. 97*2fe8fb19SBen Gras.Pp 98*2fe8fb19SBen GrasThe 99*2fe8fb19SBen Gras.Fn swprintf 100*2fe8fb19SBen Grasand 101*2fe8fb19SBen Gras.Fn vswprintf 102*2fe8fb19SBen Grasfunctions will fail if 103*2fe8fb19SBen Gras.Fa n 104*2fe8fb19SBen Grasor more wide characters were requested to be written, 105*2fe8fb19SBen Gras.Pp 106*2fe8fb19SBen GrasThe format string is composed of zero or more directives: 107*2fe8fb19SBen Grasordinary 108*2fe8fb19SBen Grascharacters (not 109*2fe8fb19SBen Gras.Cm % ) , 110*2fe8fb19SBen Graswhich are copied unchanged to the output stream; 111*2fe8fb19SBen Grasand conversion specifications, each of which results 112*2fe8fb19SBen Grasin fetching zero or more subsequent arguments. 113*2fe8fb19SBen GrasEach conversion specification is introduced by 114*2fe8fb19SBen Grasthe 115*2fe8fb19SBen Gras.Cm % 116*2fe8fb19SBen Grascharacter. 117*2fe8fb19SBen GrasThe arguments must correspond properly (after type promotion) 118*2fe8fb19SBen Graswith the conversion specifier. 119*2fe8fb19SBen GrasAfter the 120*2fe8fb19SBen Gras.Cm % , 121*2fe8fb19SBen Grasthe following appear in sequence: 122*2fe8fb19SBen Gras.Bl -bullet 123*2fe8fb19SBen Gras.It 124*2fe8fb19SBen GrasAn optional field, consisting of a decimal digit string followed by a 125*2fe8fb19SBen Gras.Cm $ , 126*2fe8fb19SBen Grasspecifying the next argument to access. 127*2fe8fb19SBen GrasIf this field is not provided, the argument following the last 128*2fe8fb19SBen Grasargument accessed will be used. 129*2fe8fb19SBen GrasArguments are numbered starting at 130*2fe8fb19SBen Gras.Cm 1 . 131*2fe8fb19SBen GrasIf unaccessed arguments in the format string are interspersed with ones that 132*2fe8fb19SBen Grasare accessed the results will be indeterminate. 133*2fe8fb19SBen Gras.It 134*2fe8fb19SBen GrasZero or more of the following flags: 135*2fe8fb19SBen Gras.Bl -tag -width ".So \ Sc (space)" 136*2fe8fb19SBen Gras.It Sq Cm # 137*2fe8fb19SBen GrasThe value should be converted to an 138*2fe8fb19SBen Gras.Dq alternate form . 139*2fe8fb19SBen GrasFor 140*2fe8fb19SBen Gras.Cm c , d , i , n , p , s , 141*2fe8fb19SBen Grasand 142*2fe8fb19SBen Gras.Cm u 143*2fe8fb19SBen Grasconversions, this option has no effect. 144*2fe8fb19SBen GrasFor 145*2fe8fb19SBen Gras.Cm o 146*2fe8fb19SBen Grasconversions, the precision of the number is increased to force the first 147*2fe8fb19SBen Grascharacter of the output string to a zero (except if a zero value is printed 148*2fe8fb19SBen Graswith an explicit precision of zero). 149*2fe8fb19SBen GrasFor 150*2fe8fb19SBen Gras.Cm x 151*2fe8fb19SBen Grasand 152*2fe8fb19SBen Gras.Cm X 153*2fe8fb19SBen Grasconversions, a non-zero result has the string 154*2fe8fb19SBen Gras.Ql 0x 155*2fe8fb19SBen Gras(or 156*2fe8fb19SBen Gras.Ql 0X 157*2fe8fb19SBen Grasfor 158*2fe8fb19SBen Gras.Cm X 159*2fe8fb19SBen Grasconversions) prepended to it. 160*2fe8fb19SBen GrasFor 161*2fe8fb19SBen Gras.Cm a , A , e , E , f , F , g , 162*2fe8fb19SBen Grasand 163*2fe8fb19SBen Gras.Cm G 164*2fe8fb19SBen Grasconversions, the result will always contain a decimal point, even if no 165*2fe8fb19SBen Grasdigits follow it (normally, a decimal point appears in the results of 166*2fe8fb19SBen Grasthose conversions only if a digit follows). 167*2fe8fb19SBen GrasFor 168*2fe8fb19SBen Gras.Cm g 169*2fe8fb19SBen Grasand 170*2fe8fb19SBen Gras.Cm G 171*2fe8fb19SBen Grasconversions, trailing zeros are not removed from the result as they 172*2fe8fb19SBen Graswould otherwise be. 173*2fe8fb19SBen Gras.It So Cm 0 Sc (zero) 174*2fe8fb19SBen GrasZero padding. 175*2fe8fb19SBen GrasFor all conversions except 176*2fe8fb19SBen Gras.Cm n , 177*2fe8fb19SBen Grasthe converted value is padded on the left with zeros rather than blanks. 178*2fe8fb19SBen GrasIf a precision is given with a numeric conversion 179*2fe8fb19SBen Gras.Cm ( d , i , o , u , i , x , 180*2fe8fb19SBen Grasand 181*2fe8fb19SBen Gras.Cm X ) , 182*2fe8fb19SBen Grasthe 183*2fe8fb19SBen Gras.Cm 0 184*2fe8fb19SBen Grasflag is ignored. 185*2fe8fb19SBen Gras.It Sq Cm \- 186*2fe8fb19SBen GrasA negative field width flag; 187*2fe8fb19SBen Grasthe converted value is to be left adjusted on the field boundary. 188*2fe8fb19SBen GrasExcept for 189*2fe8fb19SBen Gras.Cm n 190*2fe8fb19SBen Grasconversions, the converted value is padded on the right with blanks, 191*2fe8fb19SBen Grasrather than on the left with blanks or zeros. 192*2fe8fb19SBen GrasA 193*2fe8fb19SBen Gras.Cm \- 194*2fe8fb19SBen Grasoverrides a 195*2fe8fb19SBen Gras.Cm 0 196*2fe8fb19SBen Grasif both are given. 197*2fe8fb19SBen Gras.It So "\ " Sc (space) 198*2fe8fb19SBen GrasA blank should be left before a positive number 199*2fe8fb19SBen Grasproduced by a signed conversion 200*2fe8fb19SBen Gras.Cm ( a , A , d , e , E , f , F , g , G , 201*2fe8fb19SBen Grasor 202*2fe8fb19SBen Gras.Cm i ) . 203*2fe8fb19SBen Gras.It Sq Cm + 204*2fe8fb19SBen GrasA sign must always be placed before a 205*2fe8fb19SBen Grasnumber produced by a signed conversion. 206*2fe8fb19SBen GrasA 207*2fe8fb19SBen Gras.Cm + 208*2fe8fb19SBen Grasoverrides a space if both are used. 209*2fe8fb19SBen Gras.It Sq Cm ' 210*2fe8fb19SBen GrasDecimal conversions 211*2fe8fb19SBen Gras.Cm ( d , u , 212*2fe8fb19SBen Grasor 213*2fe8fb19SBen Gras.Cm i ) 214*2fe8fb19SBen Grasor the integral portion of a floating point conversion 215*2fe8fb19SBen Gras.Cm ( f 216*2fe8fb19SBen Grasor 217*2fe8fb19SBen Gras.Cm F ) 218*2fe8fb19SBen Grasshould be grouped and separated by thousands using 219*2fe8fb19SBen Grasthe non-monetary separator returned by 220*2fe8fb19SBen Gras.Xr localeconv 3 . 221*2fe8fb19SBen Gras.El 222*2fe8fb19SBen Gras.It 223*2fe8fb19SBen GrasAn optional decimal digit string specifying a minimum field width. 224*2fe8fb19SBen GrasIf the converted value has fewer characters than the field width, it will 225*2fe8fb19SBen Grasbe padded with spaces on the left (or right, if the left-adjustment 226*2fe8fb19SBen Grasflag has been given) to fill out 227*2fe8fb19SBen Grasthe field width. 228*2fe8fb19SBen Gras.It 229*2fe8fb19SBen GrasAn optional precision, in the form of a period 230*2fe8fb19SBen Gras.Cm \&. 231*2fe8fb19SBen Grasfollowed by an 232*2fe8fb19SBen Grasoptional digit string. 233*2fe8fb19SBen GrasIf the digit string is omitted, the precision is taken as zero. 234*2fe8fb19SBen GrasThis gives the minimum number of digits to appear for 235*2fe8fb19SBen Gras.Cm d , i , o , u , x , 236*2fe8fb19SBen Grasand 237*2fe8fb19SBen Gras.Cm X 238*2fe8fb19SBen Grasconversions, the number of digits to appear after the decimal-point for 239*2fe8fb19SBen Gras.Cm a , A , e , E , f , 240*2fe8fb19SBen Grasand 241*2fe8fb19SBen Gras.Cm F 242*2fe8fb19SBen Grasconversions, the maximum number of significant digits for 243*2fe8fb19SBen Gras.Cm g 244*2fe8fb19SBen Grasand 245*2fe8fb19SBen Gras.Cm G 246*2fe8fb19SBen Grasconversions, or the maximum number of characters to be printed from a 247*2fe8fb19SBen Grasstring for 248*2fe8fb19SBen Gras.Cm s 249*2fe8fb19SBen Grasconversions. 250*2fe8fb19SBen Gras.It 251*2fe8fb19SBen GrasAn optional length modifier, that specifies the size of the argument. 252*2fe8fb19SBen GrasThe following length modifiers are valid for the 253*2fe8fb19SBen Gras.Cm d , i , n , o , u , x , 254*2fe8fb19SBen Grasor 255*2fe8fb19SBen Gras.Cm X 256*2fe8fb19SBen Grasconversion: 257*2fe8fb19SBen Gras.Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *" 258*2fe8fb19SBen Gras.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n 259*2fe8fb19SBen Gras.It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *" 260*2fe8fb19SBen Gras.It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *" 261*2fe8fb19SBen Gras.It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *" 262*2fe8fb19SBen Gras.It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *" 263*2fe8fb19SBen Gras.It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *" 264*2fe8fb19SBen Gras.It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *" 265*2fe8fb19SBen Gras.It Cm z Ta (see note) Ta Vt size_t Ta (see note) 266*2fe8fb19SBen Gras.It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *" 267*2fe8fb19SBen Gras.El 268*2fe8fb19SBen Gras.Pp 269*2fe8fb19SBen GrasNote: 270*2fe8fb19SBen Grasthe 271*2fe8fb19SBen Gras.Cm t 272*2fe8fb19SBen Grasmodifier, when applied to a 273*2fe8fb19SBen Gras.Cm o , u , x , 274*2fe8fb19SBen Grasor 275*2fe8fb19SBen Gras.Cm X 276*2fe8fb19SBen Grasconversion, indicates that the argument is of an unsigned type 277*2fe8fb19SBen Grasequivalent in size to a 278*2fe8fb19SBen Gras.Vt ptrdiff_t . 279*2fe8fb19SBen GrasThe 280*2fe8fb19SBen Gras.Cm z 281*2fe8fb19SBen Grasmodifier, when applied to a 282*2fe8fb19SBen Gras.Cm d 283*2fe8fb19SBen Grasor 284*2fe8fb19SBen Gras.Cm i 285*2fe8fb19SBen Grasconversion, indicates that the argument is of a signed type equivalent in 286*2fe8fb19SBen Grassize to a 287*2fe8fb19SBen Gras.Vt size_t . 288*2fe8fb19SBen GrasSimilarly, when applied to an 289*2fe8fb19SBen Gras.Cm n 290*2fe8fb19SBen Grasconversion, it indicates that the argument is a pointer to a signed type 291*2fe8fb19SBen Grasequivalent in size to a 292*2fe8fb19SBen Gras.Vt size_t . 293*2fe8fb19SBen Gras.Pp 294*2fe8fb19SBen GrasThe following length modifier is valid for the 295*2fe8fb19SBen Gras.Cm a , A , e , E , f , F , g , 296*2fe8fb19SBen Grasor 297*2fe8fb19SBen Gras.Cm G 298*2fe8fb19SBen Grasconversion: 299*2fe8fb19SBen Gras.Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G" 300*2fe8fb19SBen Gras.It Sy Modifier Ta Cm a , A , e , E , f , F , g , G 301*2fe8fb19SBen Gras.It Cm L Ta Vt "long double" 302*2fe8fb19SBen Gras.El 303*2fe8fb19SBen Gras.Pp 304*2fe8fb19SBen GrasThe following length modifier is valid for the 305*2fe8fb19SBen Gras.Cm c 306*2fe8fb19SBen Grasor 307*2fe8fb19SBen Gras.Cm s 308*2fe8fb19SBen Grasconversion: 309*2fe8fb19SBen Gras.Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *" 310*2fe8fb19SBen Gras.It Sy Modifier Ta Cm c Ta Cm s 311*2fe8fb19SBen Gras.It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *" 312*2fe8fb19SBen Gras.El 313*2fe8fb19SBen Gras.It 314*2fe8fb19SBen GrasA character that specifies the type of conversion to be applied. 315*2fe8fb19SBen Gras.El 316*2fe8fb19SBen Gras.Pp 317*2fe8fb19SBen GrasA field width or precision, or both, may be indicated by 318*2fe8fb19SBen Grasan asterisk 319*2fe8fb19SBen Gras.Ql * 320*2fe8fb19SBen Grasor an asterisk followed by one or more decimal digits and a 321*2fe8fb19SBen Gras.Ql $ 322*2fe8fb19SBen Grasinstead of a 323*2fe8fb19SBen Grasdigit string. 324*2fe8fb19SBen GrasIn this case, an 325*2fe8fb19SBen Gras.Vt int 326*2fe8fb19SBen Grasargument supplies the field width or precision. 327*2fe8fb19SBen GrasA negative field width is treated as a left adjustment flag followed by a 328*2fe8fb19SBen Graspositive field width; a negative precision is treated as though it were 329*2fe8fb19SBen Grasmissing. 330*2fe8fb19SBen GrasIf a single format directive mixes positional 331*2fe8fb19SBen Gras.Pq Li nn$ 332*2fe8fb19SBen Grasand non-positional arguments, the results are undefined. 333*2fe8fb19SBen Gras.Pp 334*2fe8fb19SBen GrasThe conversion specifiers and their meanings are: 335*2fe8fb19SBen Gras.Bl -tag -width ".Cm diouxX" 336*2fe8fb19SBen Gras.It Cm diouxX 337*2fe8fb19SBen GrasThe 338*2fe8fb19SBen Gras.Vt int 339*2fe8fb19SBen Gras(or appropriate variant) argument is converted to signed decimal 340*2fe8fb19SBen Gras.Cm ( d 341*2fe8fb19SBen Grasand 342*2fe8fb19SBen Gras.Cm i ) , 343*2fe8fb19SBen Grasunsigned octal 344*2fe8fb19SBen Gras.Pq Cm o , 345*2fe8fb19SBen Grasunsigned decimal 346*2fe8fb19SBen Gras.Pq Cm u , 347*2fe8fb19SBen Grasor unsigned hexadecimal 348*2fe8fb19SBen Gras.Cm ( x 349*2fe8fb19SBen Grasand 350*2fe8fb19SBen Gras.Cm X ) 351*2fe8fb19SBen Grasnotation. 352*2fe8fb19SBen GrasThe letters 353*2fe8fb19SBen Gras.Dq Li abcdef 354*2fe8fb19SBen Grasare used for 355*2fe8fb19SBen Gras.Cm x 356*2fe8fb19SBen Grasconversions; the letters 357*2fe8fb19SBen Gras.Dq Li ABCDEF 358*2fe8fb19SBen Grasare used for 359*2fe8fb19SBen Gras.Cm X 360*2fe8fb19SBen Grasconversions. 361*2fe8fb19SBen GrasThe precision, if any, gives the minimum number of digits that must 362*2fe8fb19SBen Grasappear; if the converted value requires fewer digits, it is padded on 363*2fe8fb19SBen Grasthe left with zeros. 364*2fe8fb19SBen Gras.It Cm DOU 365*2fe8fb19SBen GrasThe 366*2fe8fb19SBen Gras.Vt "long int" 367*2fe8fb19SBen Grasargument is converted to signed decimal, unsigned octal, or unsigned 368*2fe8fb19SBen Grasdecimal, as if the format had been 369*2fe8fb19SBen Gras.Cm ld , lo , 370*2fe8fb19SBen Grasor 371*2fe8fb19SBen Gras.Cm lu 372*2fe8fb19SBen Grasrespectively. 373*2fe8fb19SBen GrasThese conversion characters are deprecated, and will eventually disappear. 374*2fe8fb19SBen Gras.It Cm eE 375*2fe8fb19SBen GrasThe 376*2fe8fb19SBen Gras.Vt double 377*2fe8fb19SBen Grasargument is rounded and converted in the style 378*2fe8fb19SBen Gras.Sm off 379*2fe8fb19SBen Gras.Oo \- Oc Ar d Li \&. Ar ddd Li e \*[Pm] Ar dd 380*2fe8fb19SBen Gras.Sm on 381*2fe8fb19SBen Graswhere there is one digit before the 382*2fe8fb19SBen Grasdecimal-point character 383*2fe8fb19SBen Grasand the number of digits after it is equal to the precision; 384*2fe8fb19SBen Grasif the precision is missing, 385*2fe8fb19SBen Grasit is taken as 6; if the precision is 386*2fe8fb19SBen Graszero, no decimal-point character appears. 387*2fe8fb19SBen GrasAn 388*2fe8fb19SBen Gras.Cm E 389*2fe8fb19SBen Grasconversion uses the letter 390*2fe8fb19SBen Gras.Ql E 391*2fe8fb19SBen Gras(rather than 392*2fe8fb19SBen Gras.Ql e ) 393*2fe8fb19SBen Grasto introduce the exponent. 394*2fe8fb19SBen GrasThe exponent always contains at least two digits; if the value is zero, 395*2fe8fb19SBen Grasthe exponent is 00. 396*2fe8fb19SBen Gras.Pp 397*2fe8fb19SBen GrasFor 398*2fe8fb19SBen Gras.Cm a , A , e , E , f , F , g , 399*2fe8fb19SBen Grasand 400*2fe8fb19SBen Gras.Cm G 401*2fe8fb19SBen Grasconversions, positive and negative infinity are represented as 402*2fe8fb19SBen Gras.Li inf 403*2fe8fb19SBen Grasand 404*2fe8fb19SBen Gras.Li -inf 405*2fe8fb19SBen Grasrespectively when using the lowercase conversion character, and 406*2fe8fb19SBen Gras.Li INF 407*2fe8fb19SBen Grasand 408*2fe8fb19SBen Gras.Li -INF 409*2fe8fb19SBen Grasrespectively when using the uppercase conversion character. 410*2fe8fb19SBen GrasSimilarly, NaN is represented as 411*2fe8fb19SBen Gras.Li nan 412*2fe8fb19SBen Graswhen using the lowercase conversion, and 413*2fe8fb19SBen Gras.Li NAN 414*2fe8fb19SBen Graswhen using the uppercase conversion. 415*2fe8fb19SBen Gras.It Cm fF 416*2fe8fb19SBen GrasThe 417*2fe8fb19SBen Gras.Vt double 418*2fe8fb19SBen Grasargument is rounded and converted to decimal notation in the style 419*2fe8fb19SBen Gras.Sm off 420*2fe8fb19SBen Gras.Oo \- Oc Ar ddd Li \&. Ar ddd , 421*2fe8fb19SBen Gras.Sm on 422*2fe8fb19SBen Graswhere the number of digits after the decimal-point character 423*2fe8fb19SBen Grasis equal to the precision specification. 424*2fe8fb19SBen GrasIf the precision is missing, it is taken as 6; if the precision is 425*2fe8fb19SBen Grasexplicitly zero, no decimal-point character appears. 426*2fe8fb19SBen GrasIf a decimal point appears, at least one digit appears before it. 427*2fe8fb19SBen Gras.It Cm gG 428*2fe8fb19SBen GrasThe 429*2fe8fb19SBen Gras.Vt double 430*2fe8fb19SBen Grasargument is converted in style 431*2fe8fb19SBen Gras.Cm f 432*2fe8fb19SBen Grasor 433*2fe8fb19SBen Gras.Cm e 434*2fe8fb19SBen Gras(or 435*2fe8fb19SBen Gras.Cm F 436*2fe8fb19SBen Grasor 437*2fe8fb19SBen Gras.Cm E 438*2fe8fb19SBen Grasfor 439*2fe8fb19SBen Gras.Cm G 440*2fe8fb19SBen Grasconversions). 441*2fe8fb19SBen GrasThe precision specifies the number of significant digits. 442*2fe8fb19SBen GrasIf the precision is missing, 6 digits are given; if the precision is zero, 443*2fe8fb19SBen Grasit is treated as 1. 444*2fe8fb19SBen GrasStyle 445*2fe8fb19SBen Gras.Cm e 446*2fe8fb19SBen Grasis used if the exponent from its conversion is less than \-4 or greater than 447*2fe8fb19SBen Grasor equal to the precision. 448*2fe8fb19SBen GrasTrailing zeros are removed from the fractional part of the result; a 449*2fe8fb19SBen Grasdecimal point appears only if it is followed by at least one digit. 450*2fe8fb19SBen Gras.It Cm aA 451*2fe8fb19SBen GrasThe 452*2fe8fb19SBen Gras.Vt double 453*2fe8fb19SBen Grasargument is converted to hexadecimal notation in the style 454*2fe8fb19SBen Gras.Sm off 455*2fe8fb19SBen Gras.Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \*[Pm] Oc Ar d , 456*2fe8fb19SBen Gras.Sm on 457*2fe8fb19SBen Graswhere the number of digits after the hexadecimal-point character 458*2fe8fb19SBen Grasis equal to the precision specification. 459*2fe8fb19SBen GrasIf the precision is missing, it is taken as enough to exactly 460*2fe8fb19SBen Grasrepresent the floating-point number; if the precision is 461*2fe8fb19SBen Grasexplicitly zero, no hexadecimal-point character appears. 462*2fe8fb19SBen GrasThis is an exact conversion of the mantissa+exponent internal 463*2fe8fb19SBen Grasfloating point representation; the 464*2fe8fb19SBen Gras.Sm off 465*2fe8fb19SBen Gras.Oo \- Oc Li 0x Ar h Li \&. Ar hhh 466*2fe8fb19SBen Gras.Sm on 467*2fe8fb19SBen Grasportion represents exactly the mantissa; only denormalized 468*2fe8fb19SBen Grasmantissas have a zero value to the left of the hexadecimal 469*2fe8fb19SBen Graspoint. 470*2fe8fb19SBen GrasThe 471*2fe8fb19SBen Gras.Cm p 472*2fe8fb19SBen Grasis a literal character 473*2fe8fb19SBen Gras.Ql p ; 474*2fe8fb19SBen Grasthe exponent is preceded by a positive or negative sign 475*2fe8fb19SBen Grasand is represented in decimal, using only enough characters 476*2fe8fb19SBen Grasto represent the exponent. 477*2fe8fb19SBen GrasThe 478*2fe8fb19SBen Gras.Cm A 479*2fe8fb19SBen Grasconversion uses the prefix 480*2fe8fb19SBen Gras.Dq Li 0X 481*2fe8fb19SBen Gras(rather than 482*2fe8fb19SBen Gras.Dq Li 0x ) , 483*2fe8fb19SBen Grasthe letters 484*2fe8fb19SBen Gras.Dq Li ABCDEF 485*2fe8fb19SBen Gras(rather than 486*2fe8fb19SBen Gras.Dq Li abcdef ) 487*2fe8fb19SBen Grasto represent the hex digits, and the letter 488*2fe8fb19SBen Gras.Ql P 489*2fe8fb19SBen Gras(rather than 490*2fe8fb19SBen Gras.Ql p ) 491*2fe8fb19SBen Grasto separate the mantissa and exponent. 492*2fe8fb19SBen Gras.It Cm C 493*2fe8fb19SBen GrasTreated as 494*2fe8fb19SBen Gras.Cm c 495*2fe8fb19SBen Graswith the 496*2fe8fb19SBen Gras.Cm l 497*2fe8fb19SBen Gras(ell) modifier. 498*2fe8fb19SBen Gras.It Cm c 499*2fe8fb19SBen GrasThe 500*2fe8fb19SBen Gras.Vt int 501*2fe8fb19SBen Grasargument is converted to an 502*2fe8fb19SBen Gras.Vt "unsigned char" , 503*2fe8fb19SBen Grasthen to a 504*2fe8fb19SBen Gras.Vt wchar_t 505*2fe8fb19SBen Grasas if by 506*2fe8fb19SBen Gras.Xr btowc 3 , 507*2fe8fb19SBen Grasand the resulting character is written. 508*2fe8fb19SBen Gras.Pp 509*2fe8fb19SBen GrasIf the 510*2fe8fb19SBen Gras.Cm l 511*2fe8fb19SBen Gras(ell) modifier is used, the 512*2fe8fb19SBen Gras.Vt wint_t 513*2fe8fb19SBen Grasargument is converted to a 514*2fe8fb19SBen Gras.Vt wchar_t 515*2fe8fb19SBen Grasand written. 516*2fe8fb19SBen Gras.It Cm S 517*2fe8fb19SBen GrasTreated as 518*2fe8fb19SBen Gras.Cm s 519*2fe8fb19SBen Graswith the 520*2fe8fb19SBen Gras.Cm l 521*2fe8fb19SBen Gras(ell) modifier. 522*2fe8fb19SBen Gras.It Cm s 523*2fe8fb19SBen GrasThe 524*2fe8fb19SBen Gras.Vt "char *" 525*2fe8fb19SBen Grasargument is expected to be a pointer to an array of character type (pointer 526*2fe8fb19SBen Grasto a string) containing a multibyte sequence. 527*2fe8fb19SBen GrasCharacters from the array are converted to wide characters and written up to 528*2fe8fb19SBen Gras(but not including) 529*2fe8fb19SBen Grasa terminating 530*2fe8fb19SBen Gras.Dv NUL 531*2fe8fb19SBen Grascharacter; 532*2fe8fb19SBen Grasif a precision is specified, no more than the number specified are 533*2fe8fb19SBen Graswritten. 534*2fe8fb19SBen GrasIf a precision is given, no null character 535*2fe8fb19SBen Grasneed be present; if the precision is not specified, or is greater than 536*2fe8fb19SBen Grasthe size of the array, the array must contain a terminating 537*2fe8fb19SBen Gras.Dv NUL 538*2fe8fb19SBen Grascharacter. 539*2fe8fb19SBen Gras.Pp 540*2fe8fb19SBen GrasIf the 541*2fe8fb19SBen Gras.Cm l 542*2fe8fb19SBen Gras(ell) modifier is used, the 543*2fe8fb19SBen Gras.Vt "wchar_t *" 544*2fe8fb19SBen Grasargument is expected to be a pointer to an array of wide characters 545*2fe8fb19SBen Gras(pointer to a wide string). 546*2fe8fb19SBen GrasEach wide character in the string 547*2fe8fb19SBen Grasis written. 548*2fe8fb19SBen GrasWide characters from the array are written up to (but not including) 549*2fe8fb19SBen Grasa terminating wide 550*2fe8fb19SBen Gras.Dv NUL 551*2fe8fb19SBen Grascharacter; 552*2fe8fb19SBen Grasif a precision is specified, no more than the number specified are 553*2fe8fb19SBen Graswritten (including shift sequences). 554*2fe8fb19SBen GrasIf a precision is given, no null character 555*2fe8fb19SBen Grasneed be present; if the precision is not specified, or is greater than 556*2fe8fb19SBen Grasthe number of characters in 557*2fe8fb19SBen Grasthe string, the array must contain a terminating wide 558*2fe8fb19SBen Gras.Dv NUL 559*2fe8fb19SBen Grascharacter. 560*2fe8fb19SBen Gras.It Cm p 561*2fe8fb19SBen GrasThe 562*2fe8fb19SBen Gras.Vt "void *" 563*2fe8fb19SBen Graspointer argument is printed in hexadecimal (as if by 564*2fe8fb19SBen Gras.Ql %#x 565*2fe8fb19SBen Grasor 566*2fe8fb19SBen Gras.Ql %#lx ) . 567*2fe8fb19SBen Gras.It Cm n 568*2fe8fb19SBen GrasThe number of characters written so far is stored into the 569*2fe8fb19SBen Grasinteger indicated by the 570*2fe8fb19SBen Gras.Vt "int *" 571*2fe8fb19SBen Gras(or variant) pointer argument. 572*2fe8fb19SBen GrasNo argument is converted. 573*2fe8fb19SBen Gras.It Cm % 574*2fe8fb19SBen GrasA 575*2fe8fb19SBen Gras.Ql % 576*2fe8fb19SBen Grasis written. 577*2fe8fb19SBen GrasNo argument is converted. 578*2fe8fb19SBen GrasThe complete conversion specification 579*2fe8fb19SBen Grasis 580*2fe8fb19SBen Gras.Ql %% . 581*2fe8fb19SBen Gras.El 582*2fe8fb19SBen Gras.Pp 583*2fe8fb19SBen GrasThe decimal point 584*2fe8fb19SBen Grascharacter is defined in the program's locale (category 585*2fe8fb19SBen Gras.Dv LC_NUMERIC ) . 586*2fe8fb19SBen Gras.Pp 587*2fe8fb19SBen GrasIn no case does a non-existent or small field width cause truncation of 588*2fe8fb19SBen Grasa numeric field; if the result of a conversion is wider than the field 589*2fe8fb19SBen Graswidth, the 590*2fe8fb19SBen Grasfield is expanded to contain the conversion result. 591*2fe8fb19SBen Gras.Sh RETURN VALUES 592*2fe8fb19SBen GrasThese functions return the number of characters printed 593*2fe8fb19SBen Gras(not including the trailing 594*2fe8fb19SBen Gras.Ql \e0 595*2fe8fb19SBen Grasused to end output to strings). 596*2fe8fb19SBen Gras.Sh SEE ALSO 597*2fe8fb19SBen Gras.Xr btowc 3 , 598*2fe8fb19SBen Gras.Xr fputws 3 , 599*2fe8fb19SBen Gras.Xr printf 3 , 600*2fe8fb19SBen Gras.Xr putwc 3 , 601*2fe8fb19SBen Gras.Xr setlocale 3 , 602*2fe8fb19SBen Gras.Xr wcsrtombs 3 , 603*2fe8fb19SBen Gras.Xr wscanf 3 604*2fe8fb19SBen Gras.Sh STANDARDS 605*2fe8fb19SBen GrasThe 606*2fe8fb19SBen Gras.Fn wprintf , 607*2fe8fb19SBen Gras.Fn fwprintf , 608*2fe8fb19SBen Gras.Fn swprintf , 609*2fe8fb19SBen Gras.Fn vwprintf , 610*2fe8fb19SBen Gras.Fn vfwprintf 611*2fe8fb19SBen Grasand 612*2fe8fb19SBen Gras.Fn vswprintf 613*2fe8fb19SBen Grasfunctions 614*2fe8fb19SBen Grasconform to 615*2fe8fb19SBen Gras.St -isoC-99 . 616*2fe8fb19SBen Gras.Sh SECURITY CONSIDERATIONS 617*2fe8fb19SBen GrasSubject to the caveats noted in the 618*2fe8fb19SBen Gras.Xr printf 3 . 619