diff options
Diffstat (limited to 'src/libfmt/print.3')
| -rw-r--r-- | src/libfmt/print.3 | 469 |
1 files changed, 0 insertions, 469 deletions
diff --git a/src/libfmt/print.3 b/src/libfmt/print.3 deleted file mode 100644 index 1fab0ad8..00000000 --- a/src/libfmt/print.3 +++ /dev/null @@ -1,469 +0,0 @@ -.TH PRINT 3 -.de EX -.nf -.ft B -.. -.de EE -.fi -.ft R -.. -.SH NAME -print, fprint, sprint, snprint, seprint, smprint, vfprint, vsnprint, vseprint, vsmprint \- print formatted output -.SH SYNOPSIS -.B #include <utf.h> -.PP -.B #include <fmt.h> -.PP -.ta \w'\fLchar* 'u -.B -int print(char *format, ...) -.PP -.B -int fprint(int fd, char *format, ...) -.PP -.B -int sprint(char *s, char *format, ...) -.PP -.B -int snprint(char *s, int len, char *format, ...) -.PP -.B -char* seprint(char *s, char *e, char *format, ...) -.PP -.B -char* smprint(char *format, ...) -.PP -.B -int runesprint(Rune *s, char *format, ...) -.PP -.B -int runesnprint(Rune *s, int len, char *format, ...) -.PP -.B -Rune* runeseprint(Rune *s, Rune *e, char *format, ...) -.PP -.B -Rune* runesmprint(char *format, ...) -.PP -.B -int vfprint(int fd, char *format, va_list v) -.PP -.B -int vsnprint(char *s, int len, char *format, va_list v) -.PP -.B -char* vseprint(char *s, char *e, char *format, va_list v) -.PP -.B -char* vsmprint(char *format, va_list v) -.PP -.B -int runevsnprint(Rune *s, int len, char *format, va_list v) -.PP -.B -Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v) -.PP -.B -Rune* runevsmprint(Rune *format, va_list v) -.PP -.B -.SH DESCRIPTION -.I Print -writes text to the standard output. -.I Fprint -writes to the named output -file descriptor. -.I Sprint -places text -followed by the NUL character -.RB ( \e0 ) -in consecutive bytes starting at -.IR s ; -it is the user's responsibility to ensure that -enough storage is available. -Each function returns the number of bytes -transmitted (not including the NUL -in the case of -.IR sprint ), -or -a negative value if an output error was encountered. -.PP -.I Snprint -is like -.IR sprint , -but will not place more than -.I len -bytes in -.IR s . -Its result is always NUL-terminated and holds the maximal -number of characters that can fit. -.I Seprint -is like -.IR snprint , -except that the end is indicated by a pointer -.I e -rather than a count and the return value points to the terminating NUL of the -resulting string. -.I Smprint -is like -.IR sprint , -except that it prints into and returns a string of the required length, which is -allocated by -.IR malloc (3). -.PP -The routines -.IR runesprint , -.IR runesnprint , -.IR runeseprint , -and -.I runesmprint -are the same as -.IR sprint , -.IR snprint , -.IR seprint -and -.I smprint -except that their output is rune strings instead of byte strings. -.PP -Finally, the routines -.IR vfprint , -.IR vsnprint , -.IR vseprint , -.IR vsmprint , -.IR runevsnprint , -.IR runevseprint , -and -.I runevsmprint -are like their -.BR v-less -relatives except they take as arguments a -.B va_list -parameter, so they can be called within a variadic function. -The Example section shows a representative usage. -.PP -Each of these functions -converts, formats, and prints its -trailing arguments -under control of a -.IR format -string. -The -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 -is ignored. -.PP -Each conversion specification has the following format: -.IP -.B "% [flags] verb -.PP -The verb is a single character and each flag is a single character or a -(decimal) numeric string. -Up to two numeric strings may be used; -the first is called -.IR width , -the second -.IR precision . -A period can be used to separate them, and if the period is -present then -.I width -and -.I precision -are taken to be zero if missing, otherwise they are `omitted'. -Either or both of the numbers may be replaced with the character -.BR * , -meaning that the actual number will be obtained from the argument list -as an integer. -The flags and numbers are arguments to -the -.I verb -described below. -.PP -The numeric verbs -.BR d , -.BR i , -.BR u , -.BR o , -.BR b , -.BR x , -and -.B X -format their arguments in decimal, decimal, -unsigned decimal, octal, binary, hexadecimal, and upper case hexadecimal. -Each interprets the flags -.BR 0 , -.BR h , -.BR hh , -.BR l , -.BR + , -.BR - , -.BR , , -and -.B # -to mean pad with zeros, -short, byte, long, always print a sign, left justified, commas every three digits, -and alternate format. -Also, a space character in the flag -position is like -.BR + , -but prints a space instead of a plus sign for non-negative values. -If neither -short nor long is specified, -then the argument is an -.BR int . -If an unsigned verb is specified, -then the argument is interpreted as a -positive number and no sign is output; -space and -.B + -flags are ignored for unsigned verbs. -If two -.B l -flags are given, -then the argument is interpreted as a -.B vlong -(usually an 8-byte, sometimes a 4-byte integer). -If -.I precision -is not omitted, the number is padded on the left with zeros -until at least -.I precision -digits appear. -If -.I precision -is explicitly 0, and the number is 0, -no digits are generated, and alternate formatting -does not apply. -Then, if alternate format is specified, -for -.B o -conversion, the number is preceded by a -.B 0 -if it doesn't already begin with one. -For non-zero numbers and -.B x -conversion, the number is preceded by -.BR 0x ; -for -.B X -conversion, the number is preceded by -.BR 0X . -Finally, if -.I width -is not omitted, the number is padded on the left (or right, if -left justification is specified) with enough blanks to -make the field at least -.I width -characters long. -.PP -The floating point verbs -.BR f , -.BR e , -.BR E , -.BR g , -and -.B G -take a -.B double -argument. -Each interprets the flags -.BR 0 , -.BR L -.BR + , -.BR - , -and -.B # -to mean pad with zeros, -long double argument, -always print a sign, -left justified, -and -alternate format. -.I Width -is the minimum field width and, -if the converted value takes up less than -.I width -characters, it is padded on the left (or right, if `left justified') -with spaces. -.I Precision -is the number of digits that are converted after the decimal place for -.BR e , -.BR E , -and -.B f -conversions, -and -.I precision -is the maximum number of significant digits for -.B g -and -.B G -conversions. -The -.B f -verb produces output of the form -.RB [ - ] digits [ .digits\fR]. -.B E -conversion appends an exponent -.BR E [ - ] digits , -and -.B e -conversion appends an exponent -.BR e [ - ] digits . -The -.B g -verb will output the argument in either -.B e -or -.B f -with the goal of producing the smallest output. -Also, trailing zeros are omitted from the fraction part of -the output, and a trailing decimal point appears only if it is followed -by a digit. -The -.B G -verb is similar, but uses -.B E -format instead of -.BR e . -When alternate format is specified, the result will always contain a decimal point, -and for -.B g -and -.B G -conversions, trailing zeros are not removed. -.PP -The -.B s -verb copies a string -(pointer to -.BR char ) -to the output. -The number of characters copied -.RI ( n ) -is the minimum -of the size of the string and -.IR precision . -These -.I n -characters are justified within a field of -.I width -characters as described above. -If a -.I precision -is given, it is safe for the string not to be nul-terminated -as long as it is at least -.I precision -characters (not bytes!) long. -The -.B S -verb is similar, but it interprets its pointer as an array -of runes (see -.IR utf (7)); -the runes are converted to -.SM UTF -before output. -.PP -The -.B c -verb copies a single -.B char -(promoted to -.BR int ) -justified within a field of -.I width -characters as described above. -The -.B C -verb is similar, but works on runes. -.PP -The -.B p -verb formats a pointer value. -At the moment, it is a synonym for -.BR x , -but that will change if pointers and integers are different sizes. -.PP -The -.B r -verb takes no arguments; it copies the error string returned by a call to -.IR strerror (3) -with an argument of -.IR errno. -.PP -Custom verbs may be installed using -.IR fmtinstall (3). -.SH EXAMPLE -This function prints an error message with a variable -number of arguments and then quits. -.IP -.EX -.ta 6n +6n +6n -void fatal(char *msg, ...) -{ - char buf[1024], *out; - va_list arg; - - out = vseprint(buf, buf+sizeof buf, "Fatal error: "); - va_start(arg, msg); - out = vseprint(out, buf+sizeof buf, msg, arg); - va_end(arg); - write(2, buf, out-buf); - exit(1); -} -.EE -.SH SEE ALSO -.IR fmtinstall (3), -.IR fprintf (3), -.IR utf (7) -.SH DIAGNOSTICS -Routines that write to a file descriptor or call -.IR malloc -set -.IR errstr . -.SH BUGS -The formatting is close to that specified for ANSI -.IR fprintf (3); -the main difference is that -.B b -and -.B r -are not in ANSI and some -.B C9X -verbs are missing. -Also, and distinctly not a bug, -.I print -and friends generate -.SM UTF -rather than -.SM ASCII. -.PP -There is no -.BR runeprint , -.BR runefprint , -etc. because runes are byte-order dependent and should not be written directly to a file; use the -UTF output of -.I print -or -.I fprint -instead. -Also, -.I sprint -is deprecated for safety reasons; use -.IR snprint , -.IR seprint , -or -.I smprint -instead. -Safety also precludes the existence of -.IR runesprint . |