TH PRINT 2
SH NAME
print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output
SH SYNOPSIS
B #include <u.h>
br
B #include <libc.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(char *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;
a buffered form
is described in
IR bio (2).
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 complete UTF-8 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 (2).
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
IR 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 o ,
BR b ,
BR x ,
and
B X
format their arguments in decimal,
octal, binary, hexadecimal, and upper case hexadecimal.
Each interprets the flags
BR 0 ,
BR h ,
BR hh ,
BR l ,
BR ll ,
BR u ,
BR + ,
BR - ,
BR , ,
and
B #
to mean pad with zeros,
short, byte, long, vlong, unsigned, 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 unsigned is specified,
then the argument is interpreted as a
positive number and no sign is output.
If
I precision
is not omitted, the number is padded on the left with zeros
until at least
I precision
digits appear.
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
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 + ,
BR - ,
and
B #
to mean
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 nul-terminated 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 (6));
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 single pointer or pointer-sized integer
RB ( uintptr ,
see
IR intro (2))
in hexadecimal.
PP
The
B r
verb takes no arguments; it copies the error string returned by a call to
IR errstr (2).
PP
Custom verbs may be installed using
IR fmtinstall (2).
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 = 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");
}
EE
SH SOURCE
B /sys/src/libc/fmt
SH SEE ALSO
IR fmtinstall (2),
IR fprintf (2),
IR utf (6),
IR errstr (2)
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 (2);
the main difference is that
B b
is not in ANSI and
B u
is a flag here instead of a verb.
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 .

You are viewing proxied material from sdf.org. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.