|
NAME
| |
print, fprint, sprint, snprint, seprint, smprint, runesprint,
runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint,
vsmprint, runevsnprint, runevseprint, runevsmprint – print formatted
output
|
SYNOPSIS
| |
#include <utf.h>
#include <fmt.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(3). 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 transmitted (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, except 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(3).
The routines runesprint, runesnprint, runeseprint, and runesmprint
are the same as sprint, snprint, seprint and smprint except that
their output is rune strings instead of byte strings.
Finally, the routines vfprint, vsnprint, vseprint, vsmprint, runevsnprint,
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 representative usage.
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 is ignored.
Each conversion specification has the following format:
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
below.
The numeric verbs d, i, u, o, b, x, and X format their arguments
in decimal, decimal, unsigned decimal, octal, binary, hexadecimal,
and upper case hexadecimal. Each interprets the flags 0, h, hh,
l, +, −, ,, and # 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 +, 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 an unsigned verb
is specified, then the argument is interpreted as a positive number
and no sign is output; space and + flags are ignored for unsigned
verbs. 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. If 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
o conversion, the number is preceded by a 0 if it doesn’t already
begin with one. For non-zero numbers and 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 specified) 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 0, L +, −, and # to mean pad with zeros,
long double argument, 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. Precision 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 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 G verb is similar, but uses E format instead of e. When alternate
format is specified, the
result will always contain a decimal point, and for g and G conversions,
trailing zeros are not removed.
The s verb copies a string (pointer to char) to the output. 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(7)); 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 pointer value. At the moment, it is a synonym
for x, but that will change if pointers and integers are different
sizes.
The r verb takes no arguments; it copies the error string returned
by a call to strerror(3) with an argument of errno.
Custom verbs may be installed using fmtinstall(3).
|
EXAMPLE
| |
This function prints an error message with a variable number of
arguments 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);
exit(1);
|
}
|
|
SOURCE
SEE ALSO
| |
fmtinstall(3), fprintf(3), utf(7)
|
DIAGNOSTICS
| |
Routines that write to a file descriptor or call malloc set errstr.
|
BUGS
| |
The formatting is close to that specified for ANSI fprintf(3);
the main difference is that b and r are not in ANSI and some C9X
verbs and syntax are missing. 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.
|
|
|