Return to printf.3 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man3

Annotation of 43BSDTahoe/man/man3/printf.3, revision 1.1

1.1     ! root        1: .\"    @(#)printf.3    6.5 (Berkeley) 6/5/88
        !             2: .\"
        !             3: .TH PRINTF 3S "October 22, 1987"
        !             4: .AT 3
        !             5: .SH NAME
        !             6: printf, fprintf, sprintf \- formatted output conversion
        !             7: .SH SYNOPSIS
        !             8: .B #include <stdio.h>
        !             9: .PP
        !            10: .B printf(format
        !            11: .RB [ ,
        !            12: arg ] ...
        !            13: .B )
        !            14: .br
        !            15: .B char *format;
        !            16: .PP
        !            17: .B fprintf(stream, format
        !            18: .RB [ ,
        !            19: arg ] ...
        !            20: .B )
        !            21: .br
        !            22: .SM
        !            23: .B FILE
        !            24: .B *stream;
        !            25: .br
        !            26: .B char *format;
        !            27: .PP
        !            28: .B sprintf(s, format
        !            29: .RB [ ,
        !            30: arg ] ...
        !            31: .B )
        !            32: .br
        !            33: .B char *s, *format;
        !            34: .PP
        !            35: .B #include <varargs.h>
        !            36: .br
        !            37: .B vprintf(format, args)
        !            38: .br
        !            39: .B char *format;
        !            40: .br
        !            41: .B va_list args;
        !            42: .PP
        !            43: .B vfprintf(stream, format, args)
        !            44: .br
        !            45: .B FILE *stream;
        !            46: .br
        !            47: .B char *format;
        !            48: .br
        !            49: .B va_list args;
        !            50: .PP
        !            51: .B vsprintf(s, format, args)
        !            52: .br
        !            53: .B char *s, *format;
        !            54: .br
        !            55: .B va_list args;
        !            56: .SH DESCRIPTION
        !            57: .I Printf
        !            58: places output on the standard output stream
        !            59: .BR stdout .
        !            60: .I Fprintf
        !            61: places output on the named output
        !            62: .IR stream .
        !            63: .I Sprintf
        !            64: places `output' in the string
        !            65: .IR s ,
        !            66: followed by the character `\\0'.
        !            67: Alternate forms, in which the arguments have already been
        !            68: captured using the variable-length argument facilities of
        !            69: .IR varargs (3),
        !            70: are available under the names
        !            71: .IR vprintf ,
        !            72: .IR vfprintf ,
        !            73: and
        !            74: .IR vsprintf .
        !            75: .PP
        !            76: Each of these functions converts, formats, and prints its arguments after
        !            77: the first under control of the first argument.
        !            78: The first argument is a character string which contains two types of objects:
        !            79: plain characters, which are simply copied to the output stream,
        !            80: and conversion specifications, each of which causes conversion and printing
        !            81: of the next successive
        !            82: .I arg
        !            83: .IR printf .
        !            84: .PP
        !            85: Each conversion specification is introduced by the character
        !            86: .BR % .
        !            87: The remainder of the conversion specification includes
        !            88: in the following order
        !            89: .TP
        !            90: .B \(bu
        !            91: Zero or more of the following flags:
        !            92: .RS
        !            93: .TP
        !            94: .B \(bu
        !            95: a `#' character
        !            96: specifying that the value should be converted to an ``alternate form''.
        !            97: For 
        !            98: .BR c ,
        !            99: .BR d ,
        !           100: .BR s ,
        !           101: and
        !           102: .BR u ,
        !           103: conversions, this option has no effect.  For 
        !           104: .B o
        !           105: conversions, the precision of the number is increased to force the first
        !           106: character of the output string to a zero.  For 
        !           107: .BR x ( X )
        !           108: conversion, a non-zero result has the string 
        !           109: .BR 0x ( 0X )
        !           110: prepended to it.  For 
        !           111: .BR e ,
        !           112: .BR E ,
        !           113: .BR f ,
        !           114: .BR g ,
        !           115: and
        !           116: .BR G ,
        !           117: conversions, the result will always contain a decimal point, even if no
        !           118: digits follow the point (normally, a decimal point only appears in the
        !           119: results of those conversions if a digit follows the decimal point).  For
        !           120: .B g
        !           121: and
        !           122: .B G
        !           123: conversions, trailing zeros are not removed from the result as they
        !           124: would otherwise be;
        !           125: .TP
        !           126: .B \(bu
        !           127: a minus sign `\-' which specifies
        !           128: .I "left adjustment"
        !           129: of the converted value in the indicated field;
        !           130: .TP
        !           131: .B \(bu
        !           132: a `+' character specifying that there should always be
        !           133: a sign placed before the number when using signed conversions;
        !           134: .TP
        !           135: .B \(bu
        !           136: a space specifying that a blank should be left before a positive number
        !           137: during a signed conversion.  A `+' overrides a space if both are used;
        !           138: .TP
        !           139: .B \(bu
        !           140: a zero `0' character indicating that zero-padding should be used
        !           141: rather than blank-padding.  A `\-' overrides a `0' if both are used;
        !           142: .RE
        !           143: .TP
        !           144: .B \(bu
        !           145: an optional digit string specifying a
        !           146: .I "field width;"
        !           147: if the converted value has fewer characters than the field width
        !           148: it will be blank-padded on the left (or right,
        !           149: if the left-adjustment indicator has been given) to make up the field width
        !           150: (note that a leading zero is a flag,
        !           151: but an embedded zero is part of a field width);
        !           152: .TP
        !           153: .B \(bu
        !           154: an optional period, followed by
        !           155: an optional digit string giving a
        !           156: .I precision
        !           157: which specifies the number of digits to appear after the
        !           158: decimal point, for e- and f-conversion, or the maximum number of characters
        !           159: to be printed from a string; if the digit string is missing,
        !           160: the precision is treated as zero;
        !           161: .TP
        !           162: .B \(bu
        !           163: the character
        !           164: .B l
        !           165: specifying that a following
        !           166: .BR d ,
        !           167: .BR i ,
        !           168: .BR o ,
        !           169: .BR x ,
        !           170: or
        !           171: .B u
        !           172: corresponds to a long integer
        !           173: .IR arg ,
        !           174: or that a following
        !           175: .B n
        !           176: corresponds to a pointer to a long integer
        !           177: .IR arg ;
        !           178: .TP
        !           179: .B \(bu
        !           180: the character
        !           181: .B h
        !           182: specifying that a following
        !           183: .BR d ,
        !           184: .BR i ,
        !           185: .BR o ,
        !           186: .BR x ,
        !           187: or
        !           188: .B u
        !           189: corresponds to a short integer
        !           190: .IR arg ,
        !           191: or that a following
        !           192: .B n
        !           193: corresponds to a pointer to a short integer
        !           194: .IR arg ;
        !           195: .TP
        !           196: .B \(bu
        !           197: a character which indicates the type of
        !           198: conversion to be applied.
        !           199: .PP
        !           200: A field width or precision may be `*' instead of a digit string.
        !           201: In this case an integer
        !           202: .I arg
        !           203: supplies
        !           204: the field width or precision.
        !           205: .PP
        !           206: The conversion characters
        !           207: and their meanings are
        !           208: .TP
        !           209: .B dox
        !           210: The integer
        !           211: .I arg
        !           212: is converted to signed decimal, unsigned octal, or
        !           213: unsigned hexadecimal notation respectively.
        !           214: .TP
        !           215: .B i
        !           216: An alias for `d'.
        !           217: .TP
        !           218: .B f
        !           219: The float or double
        !           220: .I arg
        !           221: is converted to decimal notation
        !           222: in the style `[\fB\-\fR]ddd.ddd'
        !           223: where the number of d's after the decimal point
        !           224: is equal to the precision specification
        !           225: for the argument.
        !           226: If the precision
        !           227: is missing,
        !           228: 6 digits are given;
        !           229: if the precision is explicitly 0, no digits and
        !           230: no decimal point are printed.
        !           231: .TP
        !           232: .B eE
        !           233: The float or double
        !           234: .I arg
        !           235: is converted in the style
        !           236: `[\fB\-\fR]d\fB.\fRddd\fBe\fR\(+-dd'
        !           237: where there is one digit before the decimal point and
        !           238: the number after is equal to the
        !           239: precision specification for the argument;
        !           240: when the precision is missing,
        !           241: 6 digits are produced.
        !           242: An uppercase E is used for `E' conversion.
        !           243: .TP
        !           244: .B gG
        !           245: The float or double
        !           246: .I arg
        !           247: is printed in style
        !           248: .B f
        !           249: or in style
        !           250: .B e
        !           251: .RB ( E )
        !           252: whichever gives full precision in minimum space.
        !           253: .TP
        !           254: .B c
        !           255: The character
        !           256: .I arg
        !           257: is printed.
        !           258: .TP
        !           259: .B s
        !           260: .I Arg
        !           261: is taken to be a string (character pointer)
        !           262: and characters from the string are printed until
        !           263: a null character or until
        !           264: the number of characters indicated by the precision
        !           265: specification is reached;
        !           266: however if the precision is 0 or missing
        !           267: all characters up to a null are printed.
        !           268: .TP
        !           269: .B u
        !           270: The unsigned integer
        !           271: .I arg
        !           272: is converted to decimal
        !           273: and printed (the result will be in the
        !           274: range 0 through MAXUINT, where MAXUINT equals 4294967295 on a VAX-11
        !           275: and 65535 on a PDP-11).
        !           276: .TP
        !           277: .B n
        !           278: .I Arg
        !           279: is taken to be a pointer to an integer (possibly
        !           280: .B short
        !           281: or
        !           282: .BR long )
        !           283: through which is stored the number of characters written
        !           284: to the output stream (or string) so far by this call to
        !           285: .B printf
        !           286: (or
        !           287: .BR fprintf ,
        !           288: etc.).
        !           289: .TP
        !           290: .B p
        !           291: .I Arg
        !           292: is taken to be a pointer to
        !           293: .BR void ;
        !           294: it is printed in style
        !           295: .BR x .
        !           296: .TP
        !           297: .B %
        !           298: Print a `%'; no argument is converted.
        !           299: .PP
        !           300: In no case does a non-existent or small field width
        !           301: cause truncation of a field;
        !           302: padding takes place only if the specified field
        !           303: width exceeds the actual width.
        !           304: Characters generated by
        !           305: .I printf
        !           306: are printed as by 
        !           307: .IR putc (3S).
        !           308: .PP
        !           309: .SH "RETURN VALUE"
        !           310: The functions all return
        !           311: the number of characters printed, or -1 if an error occurred.
        !           312: .SH EXAMPLES
        !           313: .br
        !           314: To print a date and time in the form `Sunday, July 3, 10:02',
        !           315: where
        !           316: .I weekday
        !           317: and
        !           318: .I month
        !           319: are pointers to null-terminated strings:
        !           320: .RS
        !           321: .HP
        !           322: .nh
        !           323: printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min);
        !           324: .RE
        !           325: .hy
        !           326: .PP
        !           327: To print
        !           328: .if n pi
        !           329: .if t \(*p
        !           330: to 5 decimals:
        !           331: .IP
        !           332: printf("pi = %.5f", 4*atan(1.0));
        !           333: .SH "SEE ALSO"
        !           334: putc(3S), scanf(3S)
        !           335: .SH BUGS
        !           336: The functions still supports \fI%D\fP, \fI%O\fP, and \fI%U\fP.  Do not
        !           337: use these formats, as they will be disappearing soon.

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