PRINT(3) PRINT(3) NAME print, fprint, sprint, fmtinstall - print formatted output SYNOPSIS int print(format [ , arg ] ... ) char *format; int fprint(fildes, format [ , arg ] ... ) int fildes; char *format; int sprint(s, format [ , arg ] ... ) char *s, *format; fmtinstall(c, fn) char c; int (*fn)(); strconv(s, f1, f2) char *s; extern int printcol; DESCRIPTION Print places output on the standard output. Fprint places output on the named output file descriptor; a buffered form is described in fio(3). Sprint places output followed by the null character (\0) in consecutive bytes starting at s; it is the user's responsibility to ensure that enough storage is available. Each function returns the number of charac- ters transmitted (not including the \0 in the case of sprint), or a negative value if an output error was encoun- tered. Each of these functions converts, formats, and prints its trailing arguments under control of a 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 are ignored. Each conversion specification has the following format % [flags] [[-] digits [. digits]] verb The flags modify the meaning of the conversion verb. The first (possibly negative) number is called f1, the second PRINT(3) PRINT(3) number is f2. The flags and numbers are arguments to the verb described below. The numeric verbs d, o, and x format their arguments in dec- imal, octal and hex respectively. Each interprets the flags h, l, u, to mean short, long, and unsigned. If neither short nor long is specified, then the arg is an int. If unsigned is specified, then the arg is interpreted as a pos- itive number and no sign is output. F1 is the minimum field width and, if negative, means left justified rather than right justified; in both cases, padding is done with blanks. The converted number is padded with 0 on the left to at least f2 characters. The floating point verbs f, e, and g take a double argument. No flags apply to floating point conversions. F1 is the minimum field width and, if negative, means left justified. F2 is the number of digits that are converted after the dec- imal place. The first unconverted digit has suffered deci- mal rounding. The f verb produces output of the form [-]digits[.digits]. e conversion appends an exponent e[-]digits. The g verb will output the arg in either e or f with the goal of producing the smallest output. The s verb copies a string (pointer to character) to the output. The number of characters copied (n) is the minimum of the size of the string and f2. These n characters are justified within a field of f1 characters as described above. The c verb copies a single character (int) justified within a field of f1 characters as described above. Fmtinstall is used to install your own conversions and flags. Fn should be declared as int fn(o, f1, f2, f3) void *o; int f1, f2, f3; Fn is passed a pointer o to whatever argument appears in the list to print. Fn should return the size of the argument in bytes so print can skip over it. F1 and f2 are the decoded numbers in the conversion. A missing f1 is denoted by the value zero. A missing f2 is denoted by a negative number. F3 is the logical or of all the flags seen in the conver- sion. If c is a flag, fn should return a negative number that is negated and then logically ored with any other flags and ultimately passed to a conversion routine. All inter- pretation of f1, f2, and f3 is left up to the conversion routine. The standard flags are `h'(2), `l'(1), and `u'(4). Sprint is designed to be recursive in order to help prepare output in custom conversion routines. PRINT(3) PRINT(3) The output of any conversion routine must be passed through strconv. S is the character string, f1 and f2 have the same meaning as above. Printcol indicates the position of the next output charac- ter. Tabs, backspaces and carriage returns are interpreted appropriately. EXAMPLES This adds a verb to print complex numbers. typedef struct { double r, i; } complex; complex x = { 1.5, -2.3 }; int Xconv(); main() { fmtinstall('X', Xconv); print("x = %X\n", x); } Xconv(o, f1, f2, f3) complex *o; { char str[50]; sprint(str, "(%g,%g)", o->r, o->i); strconv(str, f1, f2); return(sizeof(complex)); } SEE ALSO fio(3), printf(3) BUGS There are internal buffers which may overflow silently.