term% cat index.txt PRINT(2) System Calls Manual PRINT(2)
NAME
print, fprint, sprint, snprint, seprint, smprint, runesprint, runes‐
nprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsm‐
print, runevsnprint, runevseprint, runevsmprint - print formatted out‐
put
SYNOPSIS
#include <u.h>
#include <libc.h>
int print(char *format, ...)
int fprint(int fd, char *format, ...)
int sprint(char *s, char *format, ...)
int snprint(char *s, int len, char *format, ...)
char* seprint(char *s, char *e, char *format, ...)
char* smprint(char *format, ...)
int runesprint(Rune *s, char *format, ...)
int runesnprint(Rune *s, int len, char *format, ...)
Rune* runeseprint(Rune *s, Rune *e, char *format, ...)
Rune* runesmprint(char *format, ...)
int vfprint(int fd, char *format, va_list v)
int vsnprint(char *s, int len, char *format, va_list v)
char* vseprint(char *s, char *e, char *format, va_list v)
char* vsmprint(char *format, va_list v)
int runevsnprint(Rune *s, int len, char *format, va_list v)
Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v)
Rune* runevsmprint(Rune *format, va_list v)
DESCRIPTION
Print writes text to the standard output. Fprint writes to the named
output file descriptor; a buffered form is described in bio(2). Sprint
places text followed by the NUL 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 bytes trans‐
mitted (not including the NUL in the case of sprint), or a negative
value if an output error was encountered.
Snprint is like sprint, but will not place more than len bytes in s.
Its result is always NUL-terminated and holds the maximal number of
complete UTF-8 characters that can fit. Seprint is like snprint, ex‐
cept that the end is indicated by a pointer e rather than a count and
the return value points to the terminating NUL of the resulting string.
Smprint is like sprint, except that it prints into and returns a string
of the required length, which is allocated by malloc(2).
The routines runesprint, runesnprint, runeseprint, and runesmprint are
the same as sprint, snprint, seprint and smprint except that their out‐
put is rune strings instead of byte strings.
Finally, the routines vfprint, vsnprint, vseprint, vsmprint, runevs‐
nprint, runevseprint, and runevsmprint are like their v-less relatives
except they take as arguments a va_list parameter, so they can be
called within a variadic function. The Example section shows a repre‐
sentative usage.
Each of these functions converts, formats, and prints its trailing ar‐
guments under control of a format string. The format contains two
types of objects: plain characters, which are simply copied to the out‐
put 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 ig‐
nored.
Each conversion specification has the following format:
% [flags] verb
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 width, the second precision. A period can be used to
separate them, and if the period is present then width and precision
are taken to be zero if missing, otherwise they are `omitted'. Either
or both of the numbers may be replaced with the character *, meaning
that the actual number will be obtained from the argument list as an
integer. The flags and numbers are arguments to the verb described be‐
low.
The numeric verbs d, o, b, x, and X format their arguments in decimal,
octal, binary, hexadecimal, and upper case hexadecimal. Each inter‐
prets the flags 0, h, hh, l, u, +, -, ,, and # to mean pad with zeros,
short, byte, long, unsigned, always print a sign, left justified, com‐
mas every three digits, and alternate format. Also, a space character
in the flag position is like +, 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 int. If unsigned is specified, then the argu‐
ment is interpreted as a positive number and no sign is output. If two
l flags are given, then the argument is interpreted as a vlong (usually
an 8-byte, sometimes a 4-byte integer). If precision is not omitted,
the number is padded on the left with zeros until at least precision
digits appear. Then, if alternate format is specified, for o conver‐
sion, the number is preceded by a 0 if it doesn't already begin with
one; for x conversion, the number is preceded by 0x; for X conversion,
the number is preceded by 0X. Finally, if width is not omitted, the
number is padded on the left (or right, if left justification is speci‐
fied) with enough blanks to make the field at least width characters
long.
The floating point verbs f, e, E, g, and G take a double argument.
Each interprets the flags +, -, and # to mean always print a sign, left
justified, and alternate format. Width is the minimum field width and,
if the converted value takes up less than width characters, it is
padded on the left (or right, if `left justified') with spaces. Preci‐
sion is the number of digits that are converted after the decimal place
for e, E, and f conversions, and precision is the maximum number of
significant digits for g and G conversions. The f verb produces output
of the form [-]digits[.digits]. E conversion appends an exponent
E[-]digits, and e conversion appends an exponent e[-]digits. The g
verb will output the argument in either e or f with the goal of produc‐
ing 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 G verb is similar, but uses E format
instead of e. When alternate format is specified, the result will al‐
ways contain a decimal point, and for g and G conversions, trailing ze‐
ros are not removed.
The s verb copies a nul-terminated string (pointer to char) to the out‐
put. The number of characters copied (n) is the minimum of the size of
the string and precision. These n characters are justified within a
field of width characters as described above. If a precision is given,
it is safe for the string not to be nul-terminated as long as it is at
least precision characters (not bytes!) long. The S verb is similar,
but it interprets its pointer as an array of runes (see utf(6)); the
runes are converted to UTF before output.
The c verb copies a single char (promoted to int) justified within a
field of width characters as described above. The C verb is similar,
but works on runes.
The p verb formats a single pointer or pointer-sized integer (uintptr,
see intro(2)) in hexadecimal.
The r verb takes no arguments; it copies the error string returned by a
call to errstr(2).
Custom verbs may be installed using fmtinstall(2).
EXAMPLE
This function prints an error message with a variable number of argu‐
ments and then quits.
void fatal(char *msg, ...)
{
char buf[1024], *out;
va_list arg;
out = seprint(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);
exits("fatal error");
}
SOURCE
/sys/src/libc/fmt
SEE ALSO
fmtinstall(2), fprintf(2), utf(6), errstr(2)
DIAGNOSTICS
Routines that write to a file descriptor or call malloc set errstr.
BUGS
The formatting is close to that specified for ANSI fprintf(2); the main
difference is that b is not in ANSI and u is a flag here instead of a
verb. Also, and distinctly not a bug, print and friends generate UTF
rather than ASCII.
There is no runeprint, runefprint, etc. because runes are byte-order
dependent and should not be written directly to a file; use the UTF
output of print or fprint instead. Also, sprint is deprecated for
safety reasons; use snprint, seprint, or smprint instead. Safety also
precludes the existence of runesprint.
PRINT(2)