Return to printf.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / stdio

Annotation of 43BSDReno/lib/libc/stdio/printf.3, revision 1.1

1.1     ! root        1: .\"    @(#)printf.3    6.7 (Berkeley) 4/14/89
        !             2: .\"
        !             3: .TH PRINTF 3 "October 22, 1987"
        !             4: .AT 3
        !             5: .SH NAME
        !             6: fprintf, printf, sprintf, vprintf, vfprintf, vsprintf - formatted
        !             7: output conversion
        !             8: .SH SYNOPSIS
        !             9: .B #include <stdio.h>
        !            10: .PP
        !            11: .B printf(format
        !            12: .RB [ ,
        !            13: arg ] ...
        !            14: .B )
        !            15: .br
        !            16: .B char *format;
        !            17: .PP
        !            18: .B fprintf(stream, format
        !            19: .RB [ ,
        !            20: arg ] ...
        !            21: .B )
        !            22: .br
        !            23: .SM
        !            24: .B FILE
        !            25: .B *stream;
        !            26: .br
        !            27: .B char *format;
        !            28: .PP
        !            29: .B sprintf(s, format
        !            30: .RB [ ,
        !            31: arg ] ...
        !            32: .B )
        !            33: .br
        !            34: .B char *s, *format;
        !            35: .PP
        !            36: .B #include <varargs.h>
        !            37: .br
        !            38: .B vprintf(format, args)
        !            39: .br
        !            40: .B char *format;
        !            41: .br
        !            42: .B va_list args;
        !            43: .PP
        !            44: .B vfprintf(stream, format, args)
        !            45: .br
        !            46: .B FILE *stream;
        !            47: .br
        !            48: .B char *format;
        !            49: .br
        !            50: .B va_list args;
        !            51: .PP
        !            52: .B vsprintf(s, format, args)
        !            53: .br
        !            54: .B char *s, *format;
        !            55: .br
        !            56: .B va_list args;
        !            57: .SH DESCRIPTION
        !            58: .I Printf
        !            59: and
        !            60: .I vprintf
        !            61: place output on the standard output stream
        !            62: .BR stdout .
        !            63: .I Fprintf
        !            64: and
        !            65: .I vfprintf
        !            66: place output on the named output
        !            67: .IR stream .
        !            68: .I Sprintf
        !            69: and
        !            70: .I vsprintf
        !            71: copy into the string
        !            72: .IR s ,
        !            73: followed by the character `\e0'.
        !            74: .IR Printf ,
        !            75: .IR fprintf ,
        !            76: and
        !            77: .I sprintf
        !            78: take variadic argument lists directly, while
        !            79: .IR vprintf ,
        !            80: .IR vfprintf ,
        !            81: and
        !            82: .I vsprintf
        !            83: use the variable-length argument facilities of
        !            84: .IR varargs (3)
        !            85: and hence may be called indirectly (see examples).
        !            86: .PP
        !            87: Each function converts, formats, and prints its arguments after the
        !            88: .I format
        !            89: under control of the
        !            90: .I format
        !            91: argument; each returns the the total number of characters printed (not
        !            92: including the trailing `\e0' in
        !            93: .I sprintf
        !            94: and
        !            95: .IR vsprintf ).
        !            96: .I Format
        !            97: is a character string which contains two types of objects: plain characters,
        !            98: which are simply copied to the output stream, and conversion specifications,
        !            99: each of which causes conversion and printing of the next successive
        !           100: .IR arg .
        !           101: .PP
        !           102: Each conversion specification is introduced by the percent character (``%'').
        !           103: The remainder of the conversion specification includes, in the following
        !           104: order,
        !           105: .TP
        !           106: .B \(bu
        !           107: Zero or more of the following flags:
        !           108: .RS
        !           109: .TP
        !           110: .B \(bu
        !           111: a `#' character
        !           112: specifying that the value should be converted to an ``alternate form''.
        !           113: For 
        !           114: .BR c ,
        !           115: .BR d ,
        !           116: .BR i ,
        !           117: .BR n ,
        !           118: .BR p ,
        !           119: .BR s ,
        !           120: and
        !           121: .BR u ,
        !           122: conversions, this option has no effect.
        !           123: For 
        !           124: .B o
        !           125: conversions, the precision of the number is increased to force the first
        !           126: character of the output string to a zero (except if a zero value is printed
        !           127: with an explicit precision of zero).
        !           128: For
        !           129: .B x
        !           130: and
        !           131: .B X
        !           132: conversions, a non-zero result has the string
        !           133: .B 0x
        !           134: (or
        !           135: .B 0X
        !           136: for
        !           137: .B X
        !           138: conversions) prepended to it.
        !           139: For
        !           140: .BR e ,
        !           141: .BR E ,
        !           142: .BR f ,
        !           143: .BR g ,
        !           144: and
        !           145: .BR G ,
        !           146: conversions, the result will always contain a decimal point, even if no
        !           147: digits follow it (normally, a decimal point appears in the results of
        !           148: those conversions only if a digit follows).
        !           149: For
        !           150: .B g
        !           151: and
        !           152: .B G
        !           153: conversions, trailing zeros are not removed from the result as they
        !           154: would otherwise be.
        !           155: .TP
        !           156: .B \(bu
        !           157: A zero ``0'' character specifying zero padding.
        !           158: For all conversions except
        !           159: .BR n ,
        !           160: the converted value is padded on the left with zeros rather than blanks.
        !           161: If a precision is given with a numeric conversion (
        !           162: .BR d ,
        !           163: .BR i ,
        !           164: .BR o ,
        !           165: .BR u ,
        !           166: .BR i ,
        !           167: .BR x ,
        !           168: and
        !           169: .BR X ),
        !           170: the ``0'' flag is ignored.
        !           171: .TP
        !           172: .B \(bu
        !           173: A minus sign (``-'') specifying left adjustment of the converted value
        !           174: in the indicated field.
        !           175: Except for
        !           176: .B n
        !           177: conversions, the converted value is padded on the right with blanks,
        !           178: rather than on the left with blanks or zeros.
        !           179: A ``-'' overrides a ``0'' if both are given.
        !           180: .TP
        !           181: .B \(bu
        !           182: A space, specifying that a blank should be left before a positive number
        !           183: produced by a signed conversion (
        !           184: .BR d ,
        !           185: .BR e ,
        !           186: .BR E ,
        !           187: .BR f ,
        !           188: .BR g ,
        !           189: .BR G ,
        !           190: or
        !           191: .BR i ).
        !           192: .TP
        !           193: .B \(bu
        !           194: a `+' character specifying that a sign always be placed before a
        !           195: number produced by a signed conversion.
        !           196: A ``+'' overrides a space if both are used.
        !           197: .RE
        !           198: .TP
        !           199: .B \(bu
        !           200: An optional digit string specifying a field width.
        !           201: If the converted value has fewer characters than the field width, it will
        !           202: be padded on the left (or right, if the left-adjustment flag is used) to
        !           203: make up the field width.
        !           204: .TP
        !           205: .B \(bu
        !           206: An optional precision, in the form of a period (``.'') followed by an
        !           207: optional digit string.  If the digit string is omitted, the precision
        !           208: is taken as zero.  This gives the minimum number of digits to appear for
        !           209: .BR d ,
        !           210: .BR i ,
        !           211: .BR o ,
        !           212: .BR u ,
        !           213: .BR x ,
        !           214: and
        !           215: .B X
        !           216: conversions, the number of digits to appear after the decimal point for
        !           217: .BR e ,
        !           218: .BR E ,
        !           219: and
        !           220: .B f
        !           221: conversions, the maximum number of significant digits for
        !           222: .B g
        !           223: and
        !           224: .B G
        !           225: conversions, or the maximum number of characters to be printed from a
        !           226: string for
        !           227: .B s
        !           228: conversions.
        !           229: .TP
        !           230: .B \(bu
        !           231: The character
        !           232: .BR h ,
        !           233: specifying that a following
        !           234: .BR d ,
        !           235: .BR i ,
        !           236: .BR o ,
        !           237: .BR u ,
        !           238: .BR x ,
        !           239: or
        !           240: .B X
        !           241: conversion corresponds to a
        !           242: .B "short int"
        !           243: or
        !           244: .B "unsigned short int"
        !           245: argument, or that a following
        !           246: .B n
        !           247: conversion corresponds to a pointer to a
        !           248: .B "short int"
        !           249: argument.
        !           250: .TP
        !           251: .B \(bu
        !           252: the character
        !           253: .B l
        !           254: (ell) specifying that a following
        !           255: .BR d ,
        !           256: .BR i ,
        !           257: .BR o ,
        !           258: .BR u ,
        !           259: .BR x ,
        !           260: or
        !           261: .B X
        !           262: conversion corresponds to a
        !           263: .B "long int"
        !           264: or
        !           265: .B "unsigned long int"
        !           266: argument, or that a following
        !           267: .B n
        !           268: conversion corresponds to a pointer to a
        !           269: .B "long int"
        !           270: argument.
        !           271: .TP
        !           272: .B \(bu
        !           273: The character
        !           274: .B L
        !           275: specifying that a following
        !           276: .BR e ,
        !           277: .BR E ,
        !           278: .BR f ,
        !           279: .BR g ,
        !           280: or
        !           281: .B G
        !           282: conversion corresponds to a
        !           283: .B "long double"
        !           284: argument (but note that long double values are not currently supported
        !           285: by the \s-2VAX\s0 and Tahoe compilers).
        !           286: .TP
        !           287: .B \(bu
        !           288: A character which indicates the type of conversion to be applied.
        !           289: .PP
        !           290: A field width or precision may be an asterisk (``*'') instead of a
        !           291: digit string.
        !           292: In this case an
        !           293: .B int
        !           294: argument supplies the value.
        !           295: A negative field width is treated as a left adjustment flag followed by a
        !           296: positive field width; a negative precision is treated as though it were
        !           297: missing.
        !           298: .PP
        !           299: The conversion characters and their meanings are:
        !           300: .TP
        !           301: .B diouxX
        !           302: The
        !           303: .B int
        !           304: (or appropriate variant) argument is converted to signed decimal
        !           305: .RB ( d " and " i ),
        !           306: unsigned octal
        !           307: .RB ( o ),
        !           308: unsigned decimal
        !           309: .RB ( u ),
        !           310: or unsigned hexadecimal
        !           311: .RB ( x " and " X )
        !           312: notation respectively.  The letters
        !           313: .B abcdef
        !           314: are used for
        !           315: .B x
        !           316: conversions; the letters
        !           317: .B ABCDEF
        !           318: are used for
        !           319: .B X
        !           320: conversions.
        !           321: The precision, if any, gives the minimum number of digits that must
        !           322: appear; if the converted value requires fewer digits, it is padded on
        !           323: the left with zeros.
        !           324: .TP
        !           325: .B DOU
        !           326: The
        !           327: .B "long int"
        !           328: argument is converted to signed decimal, unsigned octal, or unsigned
        !           329: decimal, as if the format had been
        !           330: .BR ld ,
        !           331: .BR lo ,
        !           332: or
        !           333: .B lu
        !           334: respectively.
        !           335: These conversion characters are deprecated, and will eventually disappear.
        !           336: .TP 8
        !           337: .B eE
        !           338: The
        !           339: .B double
        !           340: argument is rounded and converted in the style
        !           341: `[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd' where there is one digit before the
        !           342: decimal point and the number after is equal to the precision specification
        !           343: for the argument.
        !           344: If the precision is missing, 6 digits are given; if the precision is
        !           345: explicitly zero, no decimal point appears.
        !           346: An
        !           347: .B E
        !           348: conversion uses the letter
        !           349: .B E
        !           350: (rather than
        !           351: .BR e )
        !           352: to introduce the exponent.
        !           353: The exponent always contains at least two digits; if the value is zero,
        !           354: the exponent is 00.
        !           355: .TP 8
        !           356: .B f
        !           357: The
        !           358: .B double
        !           359: argument is rounded and converted to decimal notation in the style
        !           360: `[\fB\-\fR]ddd.ddd' where the number of digits after the decimal point
        !           361: is equal to the precision.
        !           362: If the precision is missing, 6 digits are given; if the precision is
        !           363: explicitly 0, no digits and no decimal point are printed.
        !           364: If a decimal point appears, at least one digit appears before it.
        !           365: .TP 8
        !           366: .B g
        !           367: The
        !           368: .B double
        !           369: argument is printed in style
        !           370: .B f
        !           371: or
        !           372: .B e
        !           373: (or
        !           374: .B E
        !           375: for
        !           376: .B G
        !           377: conversions).
        !           378: The precision specifies the number of significant digits.
        !           379: If the precision is missing, 6 digits are given; if the precision is zero,
        !           380: it is treated as 1.
        !           381: Style
        !           382: .B e
        !           383: is used if the exponent from its conversion is less than -4 or greater than
        !           384: or equal to the precision.
        !           385: Trailing zeros are removed from the fractional part of the result; a
        !           386: decimal point appears only if it is followed by at least one digit.
        !           387: .TP 8
        !           388: .B c
        !           389: The
        !           390: .B int
        !           391: argument is converted to an
        !           392: .B "unsigned char",
        !           393: and the resulting character is printed.
        !           394: .TP 8
        !           395: .B s
        !           396: The
        !           397: .B "char *"
        !           398: argument is taken to be a string (character pointer).
        !           399: Characters from the string are printed until a null character is reached,
        !           400: or until the number of characters indicated by the precision have been
        !           401: printed, whichever occurs first; if a precision is given, no null character
        !           402: need be present.
        !           403: .TP 8
        !           404: .B p
        !           405: The
        !           406: .B "void *"
        !           407: pointer argument is printed in hexadecimal (as if by ``%x'' or ``%lx'').
        !           408: .TP 8
        !           409: .B n
        !           410: The number of characters written so far is stored into the
        !           411: integer indicated by the
        !           412: .B "int *"
        !           413: (or variant) pointer argument.
        !           414: No argument is converted.
        !           415: .TP 8
        !           416: .B %
        !           417: Prints a `%'; no argument is converted.
        !           418: .PP
        !           419: In no case does a non-existent or small field width cause truncation of
        !           420: a field; if the result of a conversion is wider than the field width, the
        !           421: field is expanded to contain it.
        !           422: Similarly, padding takes place only if the specified field width exceeds
        !           423: the actual width.
        !           424: .PP
        !           425: .SH EXAMPLES
        !           426: .br
        !           427: To print a date and time in the form `Sunday, July 3, 10:02',
        !           428: where
        !           429: .I weekday
        !           430: and
        !           431: .I month
        !           432: are pointers to null-terminated strings:
        !           433: .RS
        !           434: .HP
        !           435: .nh
        !           436: printf("%s, %s %d, %02d:%.2d", weekday, month, day, hour, min);
        !           437: .RE
        !           438: .hy
        !           439: .PP
        !           440: To print
        !           441: .if n pi
        !           442: .if t \(*p
        !           443: to 5 decimals:
        !           444: .IP
        !           445: printf("pi = %.5f", 4*atan(1.0));
        !           446: .PP
        !           447: To allocate a 128 byte string and print into it:
        !           448: .RS
        !           449: .nf
        !           450: .ta 1i 2i
        !           451: .sp
        !           452: #include <stdio.h>
        !           453: #include <varargs.h>
        !           454: char *newfmt(va_alist)
        !           455:        va_dcl
        !           456: {
        !           457:        char *p, *malloc(), fmt;
        !           458:        va_list ap;
        !           459:        if ((p = malloc(128)) == NULL)
        !           460:                return (NULL);
        !           461:        va_start(ap);
        !           462:        fmt = va_arg(ap, char *);
        !           463:        (void) vsprintf(p, fmt, ap);
        !           464:        va_end(ap);
        !           465:        return (p);
        !           466: }
        !           467: .RE
        !           468: .fi
        !           469: .SH "SEE ALSO"
        !           470: putc(3), scanf(3)
        !           471: .SH BUGS
        !           472: The conversion formats ``%D'', ``%O'', and ``%U'' are not standard and
        !           473: are provided only for backward compatibility.
        !           474: The effect of padding the ``%p'' format with zeros (either by the ``0''
        !           475: flag or by specifying a precision), and the benign effect (i.e., none)
        !           476: of the ``#'' flag on ``%n'' and ``%p'' conversions, as well as other
        !           477: nonsensical combinations such as ``%Ld'', are not standard; such combinations
        !           478: should be avoided.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.