.TH PRINT 10.2.SH NAMEprint, fprint, sprint, snprint, seprint, smprint, vfprint, vsnprint, vseprint, vsmprint \- print formatted output.SH SYNOPSIS.ta \w'\fLchar* 'u.Bint print(char *format, ...).PP.Bint fprint(int fd, char *format, ...).PP.Bint sprint(char *s, char *format, ...).PP.Bint snprint(char *s, int len, char *format, ...).PP.Bchar* seprint(char *s, char *e, char *format, ...).PP.Bchar* smprint(char *format, ...).PP.Bint vfprint(int fd, char *format, va_list v).PP.Bint vsnprint(char *s, int len, char *format, va_list v).PP.Bchar* vseprint(char *s, char *e, char *format, va_list v).PP.Bchar* vsmprint(char *format, va_list v).SH DESCRIPTION.I Printwrites text to the standard output..I Fprintwrites to the named outputfile descriptor;a buffered formis described in.IR bio (2)..I Sprintplaces textfollowed by the NUL character.RB ( \e0 )in consecutive bytes starting at.IR s ;it is the user's responsibility to ensure thatenough storage is available.Each function returns the number of bytestransmitted (not including the NULin the case of.IR sprint ),ora negative value if an output error was encountered..PP.I Snprintis like.IR sprint ,but will not place more than.I lenbytes in.IR s .Its result is always NUL-terminated and holds the maximalnumber of complete UTF-8 characters that can fit..I Seprintis like.IR snprint ,except that the end is indicated by a pointer.I erather than a count and the return value points to the terminating NUL of theresulting string..I Smprintis like.IR sprint ,except that it prints into and returns a string of the required length, which isallocated by.IR malloc (10.2)..PPFinally, the routines.IR vfprint ,.IR vsnprint ,.I vseprintand.I vsmprintare like their.BR v-lessrelatives except they take as arguments a.B va_listparameter, so they can be called within a variadic function.The Example section shows a representative usage..PPEach of these functionsconverts, formats, and prints itstrailing argumentsunder control of a.IR format string.Theformatcontains two types of objects:plain characters, which are simply copied to theoutput stream,and conversion specifications,each of which results in fetching ofzero or morearguments.The results are undefined if there are arguments of thewrong type or too fewarguments for the format.If the format is exhausted whilearguments remain, the excessis ignored..PPEach conversion specification has the following format:.IP.B "% [flags] verb.PPThe 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 ispresent then.I widthand.I precisionare 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 listas an integer.The flags and numbers are arguments tothe.I verbdescribed below..PPThe numeric verbs.BR d ,.BR o ,.BR b ,.BR x ,and.B Xformat their arguments in decimal,octal, binary, hexadecimal, and upper case hexadecimal.Each interprets the flags.BR 0 ,.BR h ,.BR hh ,.BR l ,.BR u ,.BR + ,.BR - ,.BR , ,and.B #to mean pad with zeros,short, byte, long, unsigned, always print a sign, left justified, commas every three digits,and alternate format.Also, a space character in the flagposition is like.BR + ,but prints a space instead of a plus sign for non-negative values.If neithershort nor long is specified,then the argument is an.BR int .If unsigned is specified,then the argument is interpreted as apositive number and no sign is output.If two.B lflags are given,then the argument is interpreted as a.B vlong(usually an 8-byte, sometimes a 4-byte integer).If.I precisionis not omitted, the number is padded on the left with zerosuntil at least.I precisiondigits appear.Then, if alternate format is specified,for.B oconversion, the number is preceded by a.B 0if it doesn't already begin with one;for.B xconversion, the number is preceded by.BR 0x ;for.B Xconversion, the number is preceded by.BR 0X .Finally, if.I widthis not omitted, the number is padded on the left (or right, ifleft justification is specified) with enough blanks tomake the field at least.I widthcharacters long..PPThe floating point verbs.BR f ,.BR e ,.BR E ,.BR g ,and.B Gtake a.B doubleargument.Each interprets the flags.BR + ,.BR - ,and.B #to meanalways print a sign,left justified,andalternate format..I Widthis the minimum field width and,if the converted value takes up less than.I widthcharacters, it is padded on the left (or right, if `left justified')with spaces..I Precisionis the number of digits that are converted after the decimal place for.BR e ,.BR E ,and.B fconversions,and.I precisionis the maximum number of significant digits for.B gand.B Gconversions.The .B fverb produces output of the form.RB [ - ] digits [ .digits\fR]..B Econversion appends an exponent.BR E [ - ] digits ,and.B econversion appends an exponent.BR e [ - ] digits .The.B gverb will output the argument in either.B eor.B fwith the goal of producing the smallest output.Also, trailing zeros are omitted from the fraction part ofthe output, and a trailing decimal point appears only if it is followedby a digit.The.B Gverb is similar, but uses.B Eformat instead of.BR e .When alternate format is specified, the result will always contain a decimal point,and for.B gand.B Gconversions, trailing zeros are not removed..PPThe.B sverb copies a string(pointer to.BR char )to the output.The number of characters copied.RI ( n )is the minimumof the size of the string and.IR precision .These.I ncharacters are justified within a field of.I widthcharacters as described above.The.B Sverb is similar, but it interprets its pointer as an arrayof runes (see.IR utf (6));the runes are converted to.SM UTFbefore output..PPThe.B cverb copies a single.B char(promoted to.BR int )justified within a field of.I widthcharacters as described above.The.B Cverb is similar, but works on runes..PPThe.B pverb formats a pointer value.At the moment, it is a synonym for.BR ux ,but that will change once pointers and integers are different sizes..PPThe.B rverb takes no arguments; it copies the error string returned by a call tothe emulated environment's`system calls'.It must not be used within the kernels.....PP...Custom verbs may be installed using....IR fmtinstall (2)..SH EXAMPLEThis function prints an error message with a variablenumber of arguments and then quits..IP.EX.ta 6n +6n +6nvoid 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); exits("fatal error");}.EE.SH SOURCE.B /lib9/fmt*.br.B /libkern/fmt*.SH SEE ALSO.IR utf (6).SH DIAGNOSTICSRoutines that write to a file descriptor or call.IR mallocset.IR errstr ..SH BUGSThe formatting is close to that specified for ANSI.IR fprintf (2);the main difference is that.B bis not in ANSI and.B uis a flag here instead of a verb.Also, and distinctly not a bug,.I printand friends generate.SM UTFrather than.SM ASCII..PPThere is no.BR runeprint ,.BR runefprint ,etc. because runes are byte-order dependent and should not be written directly to a file; use theUTF output of.I printor.I fprintinstead.Also,.I sprintis deprecated for safety reasons; use.IR snprint ,.IR seprint ,or.I smprintinstead.Safety also precludes the existence of.IR runesprint .
.TH PRINT 10.2
.SH NAME
print, fprint, sprint, snprint, seprint, smprint, vfprint, vsnprint, vseprint, vsmprint \- print formatted output
.SH SYNOPSIS
.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 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)
.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 (10.2).
.PP
Finally, the routines
.IR vfprint ,
.IR vsnprint ,
.I vseprint
and
.I vsmprint
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 u ,
.BR + ,
.BR - ,
.BR , ,
and
.B #
to mean pad with zeros,
short, byte, long, 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 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.
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 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.
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 pointer value.
At the moment, it is a synonym for
.BR ux ,
but that will change once pointers and integers are different sizes.
.PP
The
.B r
verb takes no arguments; it copies the error string returned by a call to
the emulated environment's
`system calls'.
It must not be used within the kernels.
....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 = 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);
exits("fatal error");
}
.EE
.SH SOURCE
.B /lib9/fmt*
.br
.B /libkern/fmt*
.SH SEE ALSO
.IR utf (6)
.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 .