diff options
Diffstat (limited to 'lib/libc/stdio/printf.3')
| -rw-r--r-- | lib/libc/stdio/printf.3 | 638 |
1 files changed, 638 insertions, 0 deletions
diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3 new file mode 100644 index 000000000000..70f8b99d3bbb --- /dev/null +++ b/lib/libc/stdio/printf.3 @@ -0,0 +1,638 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Chris Torek and the American National Standards Committee X3, +.\" on Information Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)printf.3 8.1 (Berkeley) 6/4/93 +.\" +.Dd June 4, 1993 +.Dt PRINTF 3 +.Os +.Sh NAME +.Nm printf , +.Nm fprintf , +.Nm sprintf , +.Nm snprintf , +.Nm vprintf , +.Nm vfprintf, +.Nm vsprintf , +.Nm vsnprintf +.Nd formatted output conversion +.Sh SYNOPSIS +.Fd #include <stdio.h> +.Ft int +.Fn printf "const char *format" ... +.Ft int +.Fn fprintf "FILE *stream" "const char *format" ... +.Ft int +.Fn sprintf "char *str" "const char *format" ... +.Ft int +.Fn snprintf "char *str" "size_t size" "const char *format" ... +.\" .Ft int +.\" .Fn smprintf "const char *format" ... +.Fd #include <stdarg.h> +.Ft int +.Fn vprintf "const char *format" "va_list ap" +.Ft int +.Fn vfprintf "FILE *stream" "const char *format" "va_list ap" +.Ft int +.Fn vsprintf "char *str" "char *format" "va_list ap" +.Ft int +.Fn vsnprintf "char *str" "size_t size" "const char *format" "va_list ap" +.\" .Ft int +.\" .Fn vsmprintf "const char *format" "va_list ap" +.Sh DESCRIPTION +The +.Fn printf +family of functions produces output according to a +.Fa format +as described below. +.Fn Printf +and +.Fn vprintf +write output to +.Em stdout, +the standard output stream; +.Fn fprintf +and +.Fn vfprintf +write output to the given output +.Fa stream ; +.Fn sprintf , +.Fn snprintf , +.Fn vsprintf , +and +.Fn vsnprintf +write to the character string +.Fa str . +.\" .IR str ; +.\" and +.\" .I smprintf +.\" and +.\" .I vsmprintf +.\" dynamically allocate a new string with +.\" .IR malloc . +These functions write the output under the control of a +.Fa format +string that specifies how subsequent arguments +(or arguments accessed via the variable-length argument facilities of +.Xr stdarg 3 ) +are converted for output. +.\" Except for +.\" .I smprintf +.\" and +.\" .IR vsmprintf , +.\" all of these functions return +These functions return +the number of characters printed +(not including the trailing +.Ql \e0 +used to end output to strings). +.\" .I Smprintf +.\" and +.\" .I vsmprintf +.\" return a pointer to a string of an appropriate length; +.\" this pointer should be passed to +.\" .I free +.\" to release the associated storage +.\" when it is no longer needed. +.\" If sufficient space is not avaliable, +.\" .I smprintf +.\" and +.\" .I vsmprintf +.\" will return +.\" .SM +.\" .BR +.Fn Snprintf +and +.Fn vsnprintf +will write at most +.Fa size Ns \-1 +of the characters printed into the output string +(the +.Fa size Ns 'th +character then gets the terminating +.Ql \e0 ) ; +if the return value is greater than or equal to the +.Fa size +argument, the string was too short +and some of the printed characters were discarded. +.Fn Sprintf +and +.Fn vsprintf +effectively assume an infinite +.Fa size . +.Pp +The format string is composed of zero or more directives: +ordinary +.\" multibyte +characters (not +.Cm % ) , +which are copied unchanged to the output stream; +and conversion specifications, each of which results +in fetching zero or more subsequent arguments. +Each conversion specification is introduced by +the character +.Cm % . +The arguments must correspond properly (after type promotion) +with the conversion specifier. +After the +.Cm % , +the following appear in sequence: +.Bl -bullet +.It +Zero or more of the following flags: +.Bl -hyphen +.It +A +.Cm # +character +specifying that the value should be converted to an ``alternate form''. +For +.Cm c , +.Cm d , +.Cm i , +.Cm n , +.Cm p , +.Cm s , +and +.Cm u , +conversions, this option has no effect. +For +.Cm o +conversions, the precision of the number is increased to force the first +character of the output string to a zero (except if a zero value is printed +with an explicit precision of zero). +For +.Cm x +and +.Cm X +conversions, a non-zero result has the string +.Ql 0x +(or +.Ql 0X +for +.Cm X +conversions) prepended to it. +For +.Cm e , +.Cm E , +.Cm f , +.Cm g , +and +.Cm G , +conversions, the result will always contain a decimal point, even if no +digits follow it (normally, a decimal point appears in the results of +those conversions only if a digit follows). +For +.Cm g +and +.Cm G +conversions, trailing zeros are not removed from the result as they +would otherwise be. +.It +A zero +.Sq Cm \&0 +character specifying zero padding. +For all conversions except +.Cm n , +the converted value is padded on the left with zeros rather than blanks. +If a precision is given with a numeric conversion +.Pf ( Mc d , +.Cm i , +.Cm o , +.Cm u , +.Cm i , +.Cm x , +and +.Cm X ) , +the +.Sq Cm \&0 +flag is ignored. +.It +A negative field width flag +.Sq Cm \- +indicates the converted value is to be left adjusted on the field boundary. +Except for +.Cm n +conversions, the converted value is padded on the right with blanks, +rather than on the left with blanks or zeros. +A +.Sq Cm \- +overrides a +.Sq Cm \&0 +if both are given. +.It +A space, specifying that a blank should be left before a positive number +produced by a signed conversion +.Pf ( Cm d , +.Cm e , +.Cm E , +.Cm f , +.Cm g , +.Cm G , +or +.Cm i ) . +.It +A +.Sq Cm + +character specifying that a sign always be placed before a +number produced by a signed conversion. +A +.Sq Cm + +overrides a space if both are used. +.El +.It +An optional decimal digit string specifying a minimum field width. +If the converted value has fewer characters than the field width, it will +be padded with spaces on the left (or right, if the left-adjustment +flag has been given) to fill out +the field width. +.It +An optional precision, in the form of a period +.Sq Cm \&. +followed by an +optional digit string. If the digit string is omitted, the precision +is taken as zero. This gives the minimum number of digits to appear for +.Cm d , +.Cm i , +.Cm o , +.Cm u , +.Cm x , +and +.Cm X +conversions, the number of digits to appear after the decimal-point for +.Cm e , +.Cm E , +and +.Cm f +conversions, the maximum number of significant digits for +.Cm g +and +.Cm G +conversions, or the maximum number of characters to be printed from a +string for +.Cm s +conversions. +.It +The optional character +.Cm h , +specifying that a following +.Cm d , +.Cm i , +.Cm o , +.Cm u , +.Cm x , +or +.Cm X +conversion corresponds to a +.Em short int +or +.Em unsigned short int +argument, or that a following +.Cm n +conversion corresponds to a pointer to a +.Em short int +argument. +.It +The optional character +.Cm l +(ell) specifying that a following +.Cm d , +.Cm i , +.Cm o , +.Cm u , +.Cm x , +or +.Cm X +conversion applies to a pointer to a +.Em long int +or +.Em unsigned long int +argument, or that a following +.Cm n +conversion corresponds to a pointer to a +.Em long int +argument. +.It +The optional character +.Cm q , +specifying that a following +.Cm d , +.Cm i , +.Cm o , +.Cm u , +.Cm x , +or +.Cm X +conversion corresponds to a +.Em quad int +or +.Em unsigned quad int +argument, or that a following +.Cm n +conversion corresponds to a pointer to a +.Em quad int +argument. +.It +The character +.Cm L +specifying that a following +.Cm e , +.Cm E , +.Cm f , +.Cm g , +or +.Cm G +conversion corresponds to a +.Em long double +argument (but note that long double values are not currently supported +by the +.Tn VAX +and +.Tn Tahoe +compilers). +.It +A character that specifies the type of conversion to be applied. +.El +.Pp +A field width or precision, or both, may be indicated by +an asterisk +.Ql * +instead of a +digit string. +In this case, an +.Em int +argument supplies the field width or precision. +A negative field width is treated as a left adjustment flag followed by a +positive field width; a negative precision is treated as though it were +missing. +.Pp +The conversion specifiers and their meanings are: +.Bl -tag -width "diouxX" +.It Cm diouxX +The +.Em int +(or appropriate variant) argument is converted to signed decimal +.Pf ( Cm d +and +.Cm i ) , +unsigned octal +.Pq Cm o , +unsigned decimal +.Pq Cm u , +or unsigned hexadecimal +.Pf ( Cm x +and +.Cm X ) +notation. The letters +.Cm abcdef +are used for +.Cm x +conversions; the letters +.Cm ABCDEF +are used for +.m X +conversions. +The precision, if any, gives the minimum number of digits that must +appear; if the converted value requires fewer digits, it is padded on +the left with zeros. +.It Cm DOU +The +.Em long int +argument is converted to signed decimal, unsigned octal, or unsigned +decimal, as if the format had been +.Cm ld , +.Cm lo , +or +.Cm lu +respectively. +These conversion characters are deprecated, and will eventually disappear. +.It Cm eE +The +.Em double +argument is rounded and converted in the style +.Sm off +.Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd +.Sm on +where there is one digit before the +decimal-point character +and the number of digits after it is equal to the precision; +if the precision is missing, +it is taken as 6; if the precision is +zero, no decimal-point character appears. +An +.Cm E +conversion uses the letter +.Cm E +(rather than +.Cm e ) +to introduce the exponent. +The exponent always contains at least two digits; if the value is zero, +the exponent is 00. +.It Cm f +The +.Em double +argument is rounded and converted to decimal notation in the style +.Sm off +.Pf [-]ddd Cm \&. No ddd , +.Sm on +where the number of digits after the decimal-point character +is equal to the precision specification. +If the precision is missing, it is taken as 6; if the precision is +explicitly zero, no decimal-point character appears. +If a decimal point appears, at least one digit appears before it. +.It Cm g +The +.Em double +argument is converted in style +.Cm f +or +.Cm e +(or +.Cm E +for +.Cm G +conversions). +The precision specifies the number of significant digits. +If the precision is missing, 6 digits are given; if the precision is zero, +it is treated as 1. +Style +.Cm e +is used if the exponent from its conversion is less than -4 or greater than +or equal to the precision. +Trailing zeros are removed from the fractional part of the result; a +decimal point appears only if it is followed by at least one digit. +.It Cm c +The +.Em int +argument is converted to an +.Em unsigned char , +and the resulting character is written. +.It Cm s +The +.Dq Em char * +argument is expected to be a pointer to an array of character type (pointer +to a string). +Characters from the array are written up to (but not including) +a terminating +.Dv NUL +character; +if a precision is specified, no more than the number specified are +written. +If a precision is given, no null character +need be present; if the precision is not specified, or is greater than +the size of the array, the array must contain a terminating +.Dv NUL +character. +.It Cm p +The +.Dq Em void * +pointer argument is printed in hexadecimal (as if by +.Ql %#x +or +.Ql %#lx ) . +.It Cm n +The number of characters written so far is stored into the +integer indicated by the +.Dq Em int * +(or variant) pointer argument. +No argument is converted. +.It Cm % +A +.Ql % +is written. No argument is converted. The complete conversion specification +is +.Ql %% . +.El +.Pp +In no case does a non-existent or small field width cause truncation of +a field; if the result of a conversion is wider than the field width, the +field is expanded to contain the conversion result. +.Pp +.Sh EXAMPLES +.br +To print a date and time in the form `Sunday, July 3, 10:02', +where +.Em weekday +and +.Em month +are pointers to strings: +.Bd -literal -offset indent +#include <stdio.h> +fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", + weekday, month, day, hour, min); +.Ed +.Pp +To print \*(Pi +to five decimal places: +.Bd -literal -offset indent +#include <math.h> +#include <stdio.h> +fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); +.Ed +.Pp +To allocate a 128 byte string and print into it: +.Bd -literal -offset indent +#include <stdio.h> +#include <stdlib.h> +#include <stdarg.h> +char *newfmt(const char *fmt, ...) +{ + char *p; + va_list ap; + if ((p = malloc(128)) == NULL) + return (NULL); + va_start(ap, fmt); + (void) vsnprintf(p, 128, fmt, ap); + va_end(ap); + return (p); +} +.Ed +.Sh SEE ALSO +.Xr printf 1 , +.Xr scanf 3 +.Sh STANDARDS +The +.Fn fprintf , +.Fn printf , +.Fn sprintf , +.Fn vprintf , +.Fn vfprintf , +and +.Fn vsprintf +functions +conform to +.St -ansiC . +.Sh HISTORY +The functions +.Fn snprintf +and +.Fn vsnprintf +are new to this release. +.Sh BUGS +The conversion formats +.Cm \&%D , +.Cm \&%O , +and +.Cm %U +are not standard and +are provided only for backward compatibility. +The effect of padding the +.Cm %p +format with zeros (either by the +.Sq Cm 0 +flag or by specifying a precision), and the benign effect (i.e., none) +of the +.Sq Cm # +flag on +.Cm %n +and +.Cm %p +conversions, as well as other +nonsensical combinations such as +.Cm %Ld , +are not standard; such combinations +should be avoided. +.Pp +Because +.Fn sprintf +and +.Fn vsprintf +assume an infinitely long string, +callers must be careful not to overflow the actual space; +this is often impossible to assure. +For safety, programmers should use the +.Fn snprintf +interface instead. +Unfortunately, this interface is not portable. |