![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to printf.3s CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man3|
Return to printf.3s CVS log | Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man3 |
1.1 root 1: .TH PRINTF 3S "1 April 1981"
2: .SH NAME
1.1.1.2 ! root 3: printf, fprintf, sprintf \- print formatted output
1.1 root 4: .SH SYNOPSIS
1.1.1.2 ! root 5: .B "#include <stdio.h>"
1.1 root 6: .PP
1.1.1.2 ! root 7: .B "int printf (format"
! 8: [
! 9: .B ,
! 10: arg ] .\|.\|.
1.1 root 11: .B )
12: .br
1.1.1.2 ! root 13: .B "char \(**format;"
1.1 root 14: .PP
1.1.1.2 ! root 15: .B "int fprintf (stream, format"
! 16: [
! 17: .B ,
! 18: arg ] .\|.\|.
1.1 root 19: .B )
20: .br
21: .SM
22: .B FILE
1.1.1.2 ! root 23: .B \(**stream;
1.1 root 24: .br
1.1.1.2 ! root 25: .B "char \(**format;"
1.1 root 26: .PP
1.1.1.2 ! root 27: .B "int sprintf (s, format"
! 28: [
! 29: .B ,
! 30: arg ] .\|.\|.
1.1 root 31: .B )
32: .br
1.1.1.2 ! root 33: .B "char \(**s, format;"
1.1 root 34: .SH DESCRIPTION
1.1.1.2 ! root 35: .I Printf\^
1.1 root 36: places output on the standard output stream
1.1.1.2 ! root 37: .IR stdout .
! 38: .I Fprintf\^
1.1 root 39: places output on the named output
40: .IR stream .
1.1.1.2 ! root 41: .I Sprintf\^
! 42: places ``output,''
! 43: followed by the null character
! 44: .RB ( \e0 ),
! 45: in consecutive bytes starting at
! 46: .RI \(** s ;
! 47: it is the user's responsibility to ensure that
! 48: enough storage is available.
! 49: Each function returns the number of characters
! 50: transmitted (not including the
! 51: .B \e0
! 52: in the case of
! 53: .IR sprintf ),
! 54: or
! 55: a negative value if an output error was encountered.
1.1 root 56: .PP
1.1.1.2 ! root 57: Each of these functions
! 58: converts, formats, and prints its
! 59: .IR arg s
! 60: under control of the
! 61: .IR format .
! 62: The
! 63: .I format\^
! 64: is a character string
! 65: that contains
! 66: two types of objects:
! 67: plain characters, which are simply copied to the
! 68: output stream,
! 69: and conversion specifications,
! 70: each of which results in fetching of
! 71: zero or more
! 72: .IR arg s.
! 73: The results are undefined if there are insufficient
! 74: .IR arg s
! 75: for the format.
! 76: If the format is exhausted while
! 77: .IR arg s
! 78: remain, the excess
! 79: .IR arg s
! 80: are simply ignored.
! 81: .PP
! 82: Each conversion specification is introduced by
! 83: the character
1.1 root 84: .BR % .
1.1.1.2 ! root 85: After the
1.1 root 86: .BR % ,
1.1.1.2 ! root 87: the following
! 88: appear in sequence:
! 89: .PP
! 90: .RS
! 91: Zero or more
! 92: .IR flags ,
! 93: which modify the meaning of
! 94: the conversion specification.
! 95: .PP
! 96: An optional decimal digit string specifying a minimum
! 97: .IR "field width" .
! 98: If the converted value has fewer characters
! 99: than the field width,
! 100: it will be padded on the left (or right,
! 101: if the left-adjustment flag `\-', described below, has been
! 102: given) to the field width.
! 103: If the field width for an s conversion is preceded by a 0, the
! 104: string is right adjusted with zero-padding on the left.
! 105: .PP
! 106: A
! 107: .I precision\^
! 108: that gives
! 109: the minimum number of digits to appear for the
! 110: .BR d ,
! 111: .BR o ,
! 112: .BR u ,
! 113: .BR x ,
! 114: or
! 115: .B X
! 116: conversions,
! 117: the number of digits to appear after the
! 118: decimal point for the
! 119: .B e
! 120: and
! 121: .B f
! 122: conversions,
! 123: the maximum number of significant digits
! 124: for the
! 125: .B g
! 126: conversion,
! 127: or the maximum number of characters
! 128: to be printed from a string in
! 129: .B s
! 130: conversion.
! 131: The precision takes the form of a period
! 132: .RB ( \&. )
! 133: followed by a decimal digit string;
! 134: a null digit string is treated as zero.
! 135: .PP
! 136: An optional
1.1 root 137: .B l
1.1.1.2 ! root 138: (ell) specifying that a following
1.1 root 139: .BR d ,
140: .BR o ,
1.1.1.2 ! root 141: .BR u ,
1.1 root 142: .BR x ,
143: or
1.1.1.2 ! root 144: .B X
! 145: conversion character applies to a long
! 146: integer
1.1 root 147: .IR arg .
1.1.1.2 ! root 148: An
! 149: .B l
! 150: before any other conversion character is ignored.
! 151: .PP
! 152: A character that indicates the type of
1.1 root 153: conversion to be applied.
1.1.1.2 ! root 154: .RE
1.1 root 155: .PP
1.1.1.2 ! root 156: A field width or precision may be
! 157: indicated by an asterisk
! 158: .RB ( \(** )
! 159: instead of a digit string.
! 160: In this case, an integer
! 161: .I arg\^
1.1 root 162: supplies
163: the field width or precision.
1.1.1.2 ! root 164: The
! 165: .I arg\^
! 166: that is actually converted is not fetched until
! 167: the conversion letter is seen, so the
! 168: .IR arg s
! 169: specifying field width or precision must appear
! 170: .I before\^
! 171: the
! 172: .I arg\^
! 173: (if any) to be converted.
! 174: .PP
! 175: The flag characters and their meanings are:
! 176: .PD 0
! 177: .TP 10
! 178: .B \-
! 179: The result of the conversion will be left-justified within the field.
! 180: .TP
! 181: .B +
! 182: The result of a signed
! 183: conversion will always begin with a sign
! 184: .RB ( +
! 185: or
! 186: .BR \- ).
! 187: .TP
! 188: blank
! 189: If the first character of a signed conversion is not a sign, a blank
! 190: will be prefixed to the result.
! 191: This implies that if the blank and
! 192: .B +
! 193: flags both appear, the blank flag will be ignored.
! 194: .TP
! 195: .B #
! 196: This flag specifies that the value is to be converted
! 197: to an ``alternate form.''\
! 198: For
! 199: .BR c ,
! 200: .BR d ,
! 201: .BR s ,
! 202: and
! 203: .B u
! 204: conversions, the flag has no effect.
! 205: For
! 206: .B o
! 207: conversion, it increases the precision to force
! 208: the first digit of the result to be a zero.
! 209: For
! 210: .B x or X
! 211: conversion, a non-zero result will have
! 212: .B 0x or 0X
! 213: prefixed to it.
! 214: For
! 215: .BR e ,
! 216: .BR E ,
! 217: .BR f ,
! 218: .BR g ,
! 219: and
! 220: .B G
! 221: conversions, the result will always contain a decimal point,
! 222: even if no digits follow the point (normally, a decimal point
! 223: appears in the result of these conversions only if a digit
! 224: follows it).
! 225: For
! 226: .B g
! 227: and
! 228: .B G
! 229: conversions, trailing zeroes will
! 230: .I not\^
! 231: be removed from the result
! 232: (which they normally are).
! 233: .PD
1.1 root 234: .PP
235: The conversion characters
1.1.1.2 ! root 236: and their meanings are:
! 237: .PP
! 238: .PD 0
! 239: .TP 10
! 240: \f3d\fP,\f3o\fP,\f3u\fP,\f3x\fP,\f3X\fP
1.1 root 241: The integer
1.1.1.2 ! root 242: .I arg\^
! 243: is converted to signed decimal,
! 244: unsigned octal, decimal, or
! 245: hexadecimal notation
! 246: .RB ( x
! 247: and
! 248: .BR X ),
! 249: respectively;
! 250: the letters
! 251: .B abcdef
! 252: are used for
! 253: .B x
! 254: conversion and the letters
! 255: .SM
! 256: .B ABCDEF
! 257: for
! 258: .B X
! 259: conversion.
! 260: The precision specifies the minimum number of digits
! 261: to appear; if the value being converted can be represented
! 262: in fewer digits, it will be expanded with leading blanks.
! 263: (For compatibility with older versions,
! 264: padding with leading zeroes may alternatively be specified by
! 265: prepending a zero to the field width.
! 266: This does not imply an octal value for the field width.)
! 267: The default precision is 1.
! 268: The result of converting a zero value with a precision
! 269: of zero is a null string.
1.1 root 270: .TP
1.1.1.2 ! root 271: .BR f
1.1 root 272: The float or double
1.1.1.2 ! root 273: .I arg\^
1.1 root 274: is converted to decimal notation
1.1.1.2 ! root 275: in the style ``[\f3\-\fP]ddd\f3.\fPddd,''
! 276: where the number of digits after the decimal point
! 277: is equal to the precision specification.
1.1 root 278: If the precision
279: is missing,
1.1.1.2 ! root 280: six digits are output;
! 281: if the precision is explicitly 0,
! 282: no decimal point appears.
1.1 root 283: .TP
1.1.1.2 ! root 284: .BR e , E
1.1 root 285: The float or double
1.1.1.2 ! root 286: .I arg\^
1.1 root 287: is converted in the style
1.1.1.2 ! root 288: ``[\f3\-\fP]d\f3.\fPddd\f3e\(+-\fPdd,''
1.1 root 289: where there is one digit before the decimal point and
1.1.1.2 ! root 290: the number of digits after it is equal to the
! 291: precision;
1.1 root 292: when the precision is missing,
1.1.1.2 ! root 293: six digits are produced;
! 294: if the precision is zero, no decimal point appears.
! 295: The
! 296: .B E
! 297: format code will produce a number with
! 298: .B E
! 299: instead of
! 300: .B e
! 301: introducing the exponent.
! 302: The exponent always contains at least two digits.
1.1 root 303: .TP
1.1.1.2 ! root 304: .BR g , G
1.1 root 305: The float or double
1.1.1.2 ! root 306: .I arg\^
1.1 root 307: is printed in style
1.1.1.2 ! root 308: .BR f
! 309: or
! 310: .BR e
! 311: (or in style
! 312: .B E
! 313: in the case of a
! 314: .B G
! 315: format code),
! 316: with the precision specifying the number of significant digits.
! 317: The style used depends on the value converted:
1.1 root 318: style
1.1.1.2 ! root 319: .B e
! 320: will be used only if the exponent resulting from
! 321: the conversion is less than \-4 or greater than the precision.
! 322: Trailing zeroes are removed from the result; a decimal point
! 323: appears only if it is followed by a digit.
1.1 root 324: .TP
325: .B c
326: The character
1.1.1.2 ! root 327: .I arg\^
1.1 root 328: is printed.
329: .TP
330: .B s
1.1.1.2 ! root 331: The
! 332: .I arg\^
1.1 root 333: is taken to be a string (character pointer)
334: and characters from the string are printed until
1.1.1.2 ! root 335: a null character
! 336: .RB ( \e0 )
! 337: is encountered or
1.1 root 338: the number of characters indicated by the precision
1.1.1.2 ! root 339: specification is reached.
! 340: If the precision is missing, it is taken to be infinite, so
! 341: all characters up to the first null character are printed.
! 342: A
! 343: .SM NULL
! 344: value for
! 345: .I arg\^
! 346: will yield undefined results.
1.1 root 347: .TP
348: .B %
1.1.1.2 ! root 349: Print a
! 350: .BR % ;
! 351: no argument is converted.
! 352: .PD
1.1 root 353: .PP
354: In no case does a non-existent or small field width
355: cause truncation of a field;
1.1.1.2 ! root 356: if the result of a conversion is wider than the field width,
! 357: the field is simply expanded to contain the conversion result.
1.1 root 358: Characters generated by
1.1.1.2 ! root 359: .I printf\^
! 360: and
! 361: .I fprintf\^
! 362: are printed as if
! 363: .IR putc (3S)
! 364: had been called.
! 365: .SH EXAMPLES
! 366: To print a date and time in the form ``Sunday, July 3, 10:02,''
1.1 root 367: where
1.1.1.2 ! root 368: .I weekday\^
1.1 root 369: and
1.1.1.2 ! root 370: .I month\^
1.1 root 371: are pointers to null-terminated strings:
372: .RS
373: .nh
1.1.1.2 ! root 374: .PP
! 375: printf("%s,\ %s\ %d,\ %d\fB:\fP%\fB.\fP2d",\ weekday,\ month,\ day,\ hour,\ min);
1.1 root 376: .RE
377: .PP
1.1.1.2 ! root 378: .hy 14
1.1 root 379: To print
1.1.1.2 ! root 380: .if n .I pi\^
1.1 root 381: .if t \(*p
1.1.1.2 ! root 382: to 5 decimal places:
! 383: .RS
! 384: .PP
! 385: printf("pi \|= \|%\f3.\fP5f", \|4 \(** atan(1\f3.\fP0));
! 386: .RE
! 387: .SH SEE ALSO
! 388: ecvt(3C),
1.1 root 389: putc(3S),
390: scanf(3S),
1.1.1.2 ! root 391: stdio(3S).
! 392: .\" %W% of %G%
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.