diff options
Diffstat (limited to 'static/plan9-4e/man2/fprintf.2')
| -rw-r--r-- | static/plan9-4e/man2/fprintf.2 | 504 |
1 files changed, 504 insertions, 0 deletions
diff --git a/static/plan9-4e/man2/fprintf.2 b/static/plan9-4e/man2/fprintf.2 new file mode 100644 index 00000000..934f4554 --- /dev/null +++ b/static/plan9-4e/man2/fprintf.2 @@ -0,0 +1,504 @@ +.TH FPRINTF 2 +.SH NAME +fprintf, printf, sprintf, snprintf, vfprintf, vprintf, vsprintf, vsnprintf \- print formatted output +.SH SYNOPSIS +.B #include <stdio.h> +.PP +.B +int fprintf(FILE *f, char *format, ...) +.PP +.B +int printf(char *format, ...) +.PP +.B +int sprintf(char *s, char *format, ...) +.PP +.B +int snprintf(char *s, int n, char *format, ...) +.PP +.B +int vfprintf(FILE *f, char *format, va_list args) +.PP +.B +int vprintf(char *format, va_list args) +.PP +.B +int vsprintf(char *s, char *format, va_list args) +.PP +.B +int vsnprintf(char *s, int n, char *format, va_list args) +.SH DESCRIPTION +.I Fprintf +places output on the named output stream +.I f +(see +.IR fopen (2)). +.I Printf +places output on the standard output stream +.IR stdout . +.I Sprintf +places output +followed by the null character +.RB ( \e0 ) +in consecutive bytes starting at +.IR s ; +it is the user's responsibility to ensure that +enough storage is available. +.I Snprintf +is like +.I sprintf +but writes at most +.I n +bytes (including the null character) +into +.IR s . +.IR Vfprintf , +.IR vprintf , +.IR vsnprintf , +and +.I vsprintf +are the same, except the +.I args +argument is the argument list of the +calling function, and the effect is as if the calling function's +argument list from that point on is passed to the +.I printf +routines. +.PP +Each function returns the number of characters +transmitted (not including the +.B \e0 +in the case of +.IR sprintf +and friends), +or +a negative value if an output error was encountered. +.PP +These functions +convert, format, and print their +trailing arguments +under control of a +.IR format +string. +The +.I format +contains two types of objects: +plain characters, which are simply copied to the +output stream, +and conversion specifications, +each of which results in fetching of +zero or more +arguments. +The results are undefined if there are arguments of the +wrong type or too few +arguments for the format. +If the format is exhausted while +arguments remain, the excess +are ignored. +.PP +Each conversion specification is introduced by +the character +.BR % . +After the +.BR % , +the following +appear in sequence: +.PP +.RS +Zero or more +.IR flags , +which modify the meaning of +the conversion specification. +.PP +An optional decimal digit string specifying a minimum +.IR "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, described later, has been given) +to the field width. +.PP +An optional +.I precision\^ +that gives +the minimum number of digits to appear for the +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.B X +conversions, +the number of digits to appear after the +decimal point for the +.BR e , +.BR E , +and +.B f +conversions, +the maximum number of significant digits +for the +.B g +and +.B G +conversions, +or the maximum number of characters +to be written from a string in +.B s +conversion. +The precision takes the form of a period +.RB ( \&. ) +followed by an optional decimal integer; +if the integer is omitted, it is treated as zero. +.PP +An optional +.B h +specifying that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x +or +.BR X +conversion specifier applies to a +.B short +.B int +or +.B unsigned +.B short +argument (the argument will have been promoted according to the integral +promotions, and its value shall be converted to +.B short +or +.B unsigned +.B short +before printing); +an optional +.B h +specifying that a following +.B n +conversion specifier applies to a pointer to a +.B short +argument; +an optional +.B l +(ell) specifying that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.B X +conversion character applies to a +.B long +or +.B unsigned +.B long +argument; +an optional +.B l +specifying that a following +.B n +conversion specifier applies to a pointer to a +.B long +.B int +argument; +or an optional +.B L +specifying that a following +.BR e , +.BR E , +.BR f , +.BR g , +or +.B G +conversion specifier applies to a +.B long double +argument. +If an +.BR h , +.BR l , +or +.B L +appears with any other conversion specifier, the behavior is undefined. +.PP +A character that indicates the type of +conversion to be applied. +.RE +.PP +A field width or precision, or both, may be +indicated by an asterisk +.RB ( * ) +instead of a digit string. +In this case, an +.B int +.I arg\^ +supplies +the field width or precision. +The arguments specifying field width or precision, or both, +shall appear (in that order) before the argument (if any) to be converted. +A negative field width argument is taken as a +.B - +flag followed by a positive field width. +A negative precision is taken as if it were missing. +.PP +The flag characters and their meanings are: +.PD 0 +.TP 10 +.B - +The result of the conversion is left-justified within the field. +.TP +.B + +The result of a signed +conversion always begins with a sign +.RB ( + +or +.BR - ). +.TP +blank +If the first character of a signed conversion is not a sign, +or a signed conversion results in no characters, +a blank +is prefixed to the result. +This implies that if the blank and +.B + +flags both appear, the blank flag is ignored. +.TP +.B # +The result is to be converted +to an ``alternate form.'' +For +.B o +conversion, it increases the precision to force +the first digit of the result to be a zero. +For +.B x +or +.B X +conversion, a non-zero result has +.B 0x +or +.B 0X +prefixed to it. +For +.BR e , +.BR E , +.BR f , +.BR g , +and +.B G +conversions, the result always contains a decimal point, +even if no digits follow the point (normally, a decimal point +appears in the result of these conversions only if a digit +follows it). +For +.B g +and +.B G +conversions, trailing zeros are +.I not\^ +be removed from the result +as they normally are. +For other conversions, the behavior is undefined. +.TP +.B 0 +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +.BR e , +.BR E , +.BR f , +.BR g , +and +.B G +conversions, leading zeros (following any indication of sign or base) +are used to pad the field width; no space padding is performed. +If the +.B 0 +and +.B - +flags both appear, the +.B 0 +flag will be ignored. +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.B X +conversions, if a precision is specified, the +.B 0 +flag will be ignored. +For other conversions, the behavior is undefined. +.PD +.PP +The conversion characters +and their meanings are: +.PP +.PD 0 +.TP 10 +\fLd\fP,\fLo\fP,\fLu\fP,\fLx\fP,\fLX\fP +The integer +.I arg\^ +is converted to signed decimal +.RB ( d +or +.BR i ), +unsigned octal +.RB ( o ), +unsigned decimal +.RB ( u ), +or unsigned hexadecimal notation +.RB ( x +or +.BR X ); +the letters +.B abcdef +are used for +.B x +conversion and the letters +.B ABCDEF +for +.B X +conversion. +The precision specifies the minimum number of digits +to appear; if the value being converted can be represented +in fewer digits, it is expanded with leading zeros. +The default precision is 1. +The result of converting a zero value with a precision +of zero is no characters. +.TP +.BR f +The +.B double +argument is converted to decimal notation +in the style +[\-]\fIddd\fL.\fIddd\fR, +where the number of digits after the decimal point +is equal to the precision specification. +If the precision +is missing, +it is taken as 6; +if the precision is explicitly +.LR 0 , +no decimal point appears. +.TP +.BR e , E +The +.B double +argument is converted in the style +[\-]\fId\fL.\fIddd\fLe\fR±\fIdd\fR, +where there is one digit before the decimal point and +the number of digits after it is equal to the +precision; +when the precision is missing, it is taken as 6; +if the precision is zero, no decimal point appears. +The +.B E +format code produces a number with +.B E +instead of +.B e +introducing the exponent. +The exponent always contains at least two digits. +.TP +.BR g , G +The +.B double +argument is printed in style +.BR f +or +.BR e +(or in style +.B E +in the case of a +.B G +conversion specifier), +with the precision specifying the number of significant digits. +If an explicit precision is zero, it is taken as 1. +The style used depends on the value converted: +style +.B e +is used only if the exponent resulting from +the conversion is less than \-4 +or greater than or equal to the precision. +Trailing zeros are removed from the fractional portion of the result; +a decimal point appears only if it is followed by a digit. +.TP +.B c +The +.B int +argument is converted to an +.B unsigned +.BR char , +and the resulting character is written. +.TP +.B s +The +argument is taken to be a string (character pointer) +and characters from the string are printed until +a null character +.RB ( \e0 ) +is encountered or +the number of characters indicated by the precision +specification is reached. +If the precision is missing, it is taken to be infinite, so +all characters up to the first null character are printed. +A +zero +value for +the argument yields undefined results. +.TP +.B P +The +.B void* +argument is printed in an implementation-defined way (for Plan 9: +the address as hexadecimal number). +.TP +.B n +The argument shall be a pointer to an integer into which is +.I written +the number of characters written to the output stream so far by +this call to +.IR fprintf . +No argument is converted. +.TP +.B % +Print a +.BR % ; +no argument is converted. +.PD +.PP +If a conversion specification is invalid, the behavior is undefined. +.PP +If any argument is, or points to, a union or an aggregate +(except for an array of character type using +.B %s +conversion, or a pointer cast to be a pointer to +.B void +using +.B %P +conversion), the behavior is undefined. +.PP +In no case does a nonexistent 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. +.SH SOURCE +.B /sys/src/libstdio +.SH SEE ALSO +.IR fopen (2), +.IR fscanf (2), +.IR print (2) +.SH BUGS +There is no way to print a wide character (rune); use +.IR print (2) +or +.IR bio (2). |