309 lines
17 KiB
HTML
309 lines
17 KiB
HTML
<head>
|
|
<title>print(3) - Plan 9 from User Space</title>
|
|
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
|
|
</head>
|
|
<body bgcolor=#ffffff>
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
|
<tr height=10><td>
|
|
<tr><td width=20><td>
|
|
<tr><td width=20><td><b>PRINT(3)</b><td align=right><b>PRINT(3)</b>
|
|
<tr><td width=20><td colspan=2>
|
|
<br>
|
|
<p><font size=+1><b>NAME </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
print, fprint, sprint, snprint, seprint, smprint, runesprint,
|
|
runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint,
|
|
vsmprint, runevsnprint, runevseprint, runevsmprint – print formatted
|
|
output<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>SYNOPSIS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>#include <u.h>
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>#include <libc.h>
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int print(char *format, ...)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int fprint(int fd, char *format, ...)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int sprint(char *s, char *format, ...)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int snprint(char *s, int len, char *format, ...)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>char* seprint(char *s, char *e, char *format, ...)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>char* smprint(char *format, ...)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int runesprint(Rune *s, char *format, ...)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int runesnprint(Rune *s, int len, char *format, ...)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>Rune* runeseprint(Rune *s, Rune *e, char *format, ...)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>Rune* runesmprint(char *format, ...)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int vfprint(int fd, char *format, va_list v)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int vsnprint(char *s, int len, char *format, va_list v)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>char* vseprint(char *s, char *e, char *format, va_list v)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>char* vsmprint(char *format, va_list v)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>int runevsnprint(Rune *s, int len, char *format, va_list v)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v)
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
<tt><font size=+1>Rune* runevsmprint(Rune *format, va_list v)
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
|
|
</table>
|
|
<p><font size=+1><b>DESCRIPTION </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<i>Print</i> writes text to the standard output. <i>Fprint</i> writes to the
|
|
named output file descriptor: a buffered form is described in
|
|
<a href="../man3/bio.html"><i>bio</i>(3)</a>. <i>Sprint</i> places text followed by the NUL character (<tt><font size=+1>\0</font></tt>)
|
|
in consecutive bytes starting at <i>s</i>; 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 <i>sprint</i>), or a negative value if an output error was encountered.
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Snprint</i> is like <i>sprint</i>, but will not place more than <i>len</i> bytes
|
|
in <i>s</i>. Its result is always NUL-terminated and holds the maximal
|
|
number of complete UTF-8 characters that can fit. <i>Seprint</i> is like
|
|
<i>snprint</i>, except that the end is indicated by a pointer <i>e</i> rather
|
|
than a count and the return value points to the terminating NUL
|
|
of
|
|
the resulting string. <i>Smprint</i> is like <i>sprint</i>, except that it prints
|
|
into and returns a string of the required length, which is allocated
|
|
by <a href="../man3/malloc.html"><i>malloc</i>(3)</a>.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The routines <i>runesprint</i>, <i>runesnprint</i>, <i>runeseprint</i>, and <i>runesmprint</i>
|
|
are the same as <i>sprint</i>, <i>snprint</i>, <i>seprint</i> and <i>smprint</i> except that
|
|
their output is rune strings instead of byte strings.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Finally, the routines <i>vfprint</i>, <i>vsnprint</i>, <i>vseprint</i>, <i>vsmprint</i>, <i>runevsnprint</i>,
|
|
<i>runevseprint</i>, and <i>runevsmprint</i> are like their <tt><font size=+1>v−less</font></tt> relatives
|
|
except they take as arguments a <tt><font size=+1>va_list</font></tt> parameter, so they can
|
|
be called within a variadic function. The Example section shows
|
|
a representative usage.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Each of these functions converts, formats, and prints its trailing
|
|
arguments under control of a <i>format</i> 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.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Each conversion specification has the following format:<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>% [flags] verb
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
|
|
</table>
|
|
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 <i>width</i>, the second <i>precision</i>. A period
|
|
can be used to separate them, and if the period is present then
|
|
<i>width</i> and <i>precision</i> are taken to be zero if missing, otherwise
|
|
they are ‘omitted’. Either or both of the numbers may be replaced
|
|
with the character <tt><font size=+1>*</font></tt>, 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</i> described below.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The numeric verbs <tt><font size=+1>d</font></tt>, <tt><font size=+1>o</font></tt>, <tt><font size=+1>b</font></tt>, <tt><font size=+1>x</font></tt>, and <tt><font size=+1>X</font></tt> format their arguments in
|
|
decimal, octal, binary, hexadecimal, and upper case hexadecimal.
|
|
Each interprets the flags <tt><font size=+1>0</font></tt>, <tt><font size=+1>h</font></tt>, <tt><font size=+1>hh</font></tt>, <tt><font size=+1>l</font></tt>, <tt><font size=+1>u</font></tt>, <tt><font size=+1>+</font></tt>, <tt><font size=+1>−</font></tt>, <tt><font size=+1>,</font></tt>, and <tt><font size=+1>#</font></tt> 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 <tt><font size=+1>+</font></tt>, 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 <tt><font size=+1>int</font></tt>. If unsigned
|
|
is specified, then the argument is interpreted as a positive number
|
|
and no sign is output. If two <tt><font size=+1>l</font></tt> flags are given, then
|
|
the argument is interpreted as a <tt><font size=+1>vlong</font></tt> (usually an 8-byte, sometimes
|
|
a 4-byte integer). If <i>precision</i> is not omitted, the number is
|
|
padded on the left with zeros until at least <i>precision</i> digits
|
|
appear. If <i>precision</i> 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 <tt><font size=+1>o</font></tt> conversion, the number
|
|
is preceded by a <tt><font size=+1>0</font></tt> if it doesn’t already begin with one; for <tt><font size=+1>x</font></tt>
|
|
conversion, the number is preceded by <tt><font size=+1>0x</font></tt>; for <tt><font size=+1>X</font></tt> conversion, the
|
|
number is preceded by <tt><font size=+1>0X</font></tt>. Finally, if <i>width</i> 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</i> characters
|
|
long.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The floating point verbs <tt><font size=+1>f</font></tt>, <tt><font size=+1>e</font></tt>, <tt><font size=+1>E</font></tt>, <tt><font size=+1>g</font></tt>, and <tt><font size=+1>G</font></tt> take a <tt><font size=+1>double</font></tt> argument.
|
|
Each interprets the flags <tt><font size=+1>0</font></tt>, <tt><font size=+1>L +</font></tt>, <tt><font size=+1>−</font></tt>, and <tt><font size=+1>#</font></tt> to mean pad with zeros,
|
|
long double argument, always print a sign, left justified, and
|
|
alternate format. <i>Width</i> is the minimum field width and, if the
|
|
converted value takes up less than <i>width</i> characters, it is
|
|
padded on the left (or right, if ‘left justified’) with spaces.
|
|
<i>Precision</i> is the number of digits that are converted after the
|
|
decimal place for <tt><font size=+1>e</font></tt>, <tt><font size=+1>E</font></tt>, and <tt><font size=+1>f</font></tt> conversions, and <i>precision</i> is the
|
|
maximum number of significant digits for <tt><font size=+1>g</font></tt> and <tt><font size=+1>G</font></tt> conversions.
|
|
The <tt><font size=+1>f</font></tt> verb produces output of the form [<tt><font size=+1>−</font></tt>]<tt><font size=+1>digits</font></tt>[<tt><font size=+1>.digits</font></tt>]. <tt><font size=+1>E
|
|
</font></tt>conversion appends an exponent <tt><font size=+1>E</font></tt>[<tt><font size=+1>−</font></tt>]<tt><font size=+1>digits</font></tt>, and <tt><font size=+1>e</font></tt> conversion appends
|
|
an exponent <tt><font size=+1>e</font></tt>[<tt><font size=+1>−</font></tt>]<tt><font size=+1>digits</font></tt>. The <tt><font size=+1>g</font></tt> verb will output the argument in
|
|
either <tt><font size=+1>e</font></tt> or <tt><font size=+1>f</font></tt> 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 <tt><font size=+1>G</font></tt> verb is similar, but uses <tt><font size=+1>E</font></tt> format
|
|
instead of <tt><font size=+1>e</font></tt>. When alternate format is specified, the result will
|
|
always contain a decimal point, and for <tt><font size=+1>g</font></tt> and <tt><font size=+1>G</font></tt> conversions, trailing
|
|
zeros are not removed.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The <tt><font size=+1>s</font></tt> verb copies a NUL-terminated string (pointer to <tt><font size=+1>char</font></tt>) to
|
|
the output. The number of characters copied (<i>n</i>) is the minimum
|
|
of the size of the string and <i>precision</i>. These <i>n</i> characters are
|
|
justified within a field of <i>width</i> characters as described above.
|
|
If a <i>precision</i> is given, it is safe for the string not to be nul-
|
|
terminated as long as it is at least <i>precision</i> characters (not
|
|
bytes!) long. The <tt><font size=+1>S</font></tt> verb is similar, but it interprets its pointer
|
|
as an array of runes (see <a href="../man7/utf.html"><i>utf</i>(7)</a>); the runes are converted to
|
|
UTF before output.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The <tt><font size=+1>c</font></tt> verb copies a single <tt><font size=+1>char</font></tt> (promoted to <tt><font size=+1>int</font></tt>) justified within
|
|
a field of <i>width</i> characters as described above. The <tt><font size=+1>C</font></tt> verb is
|
|
similar, but works on runes.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The <tt><font size=+1>p</font></tt> verb formats a pointer value. At the moment, it is a synonym
|
|
for <tt><font size=+1>x</font></tt>, but that will change if pointers and integers are different
|
|
sizes.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The <tt><font size=+1>r</font></tt> verb takes no arguments; it copies the error string returned
|
|
by a call to <a href="../man3/errstr.html"><i>errstr</i>(3)</a>.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Custom verbs may be installed using <a href="../man3/fmtinstall.html"><i>fmtinstall</i>(3)</a>.<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>EXAMPLE </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
This function prints an error message with a variable number of
|
|
arguments and then quits.<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>void fatal(char *msg, ...)<br>
|
|
{<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
char buf[1024], *out;<br>
|
|
va_list arg;<br>
|
|
out = seprint(buf, buf+sizeof buf, "Fatal error: ");<br>
|
|
va_start(arg, msg);<br>
|
|
out = vseprint(out, buf+sizeof buf, msg, arg);<br>
|
|
va_end(arg);<br>
|
|
write(2, buf, out−buf);<br>
|
|
exits("fatal error");<br>
|
|
|
|
</table>
|
|
}<br>
|
|
</font></tt>
|
|
</table>
|
|
|
|
</table>
|
|
<p><font size=+1><b>SOURCE </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>/usr/local/plan9/src/lib9/libfmt<br>
|
|
</font></tt>
|
|
</table>
|
|
<p><font size=+1><b>SEE ALSO </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<a href="../man3/fmtinstall.html"><i>fmtinstall</i>(3)</a>, <a href="../man3/fprintf.html"><i>fprintf</i>(3)</a>, <a href="../man7/utf.html"><i>utf</i>(7)</a><br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>DIAGNOSTICS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
Routines that write to a file descriptor or call <i>malloc</i> set <i>errstr</i>.<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>BUGS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
The formatting is close to that specified for ANSI <a href="../man3/fprintf.html"><i>fprintf</i>(3)</a>;
|
|
the main difference is that <tt><font size=+1>b</font></tt> and <tt><font size=+1>r</font></tt> are not in ANSI and <tt><font size=+1>u</font></tt> is a
|
|
flag here instead of a verb. Also, and distinctly not a bug, <i>print</i>
|
|
and friends generate UTF rather than ASCII.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
There is no <i>runeprint</i>, <i>runefprint</i>, etc. because runes are byte-order
|
|
dependent and should not be written directly to a file; use the
|
|
UTF output of <i>print</i> or <i>fprint</i> instead. Also, <i>sprint</i> is deprecated
|
|
for safety reasons; use <i>snprint</i>, <i>seprint</i>, or <i>smprint</i> instead.
|
|
Safety also precludes the existence of <i>runesprint</i>.
|
|
|
|
</table>
|
|
|
|
<td width=20>
|
|
<tr height=20><td>
|
|
</table>
|
|
<!-- TRAILER -->
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
|
<tr height=15><td width=10><td><td width=10>
|
|
<tr><td><td>
|
|
<center>
|
|
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
|
|
</center>
|
|
</table>
|
|
<!-- TRAILER -->
|
|
</body></html>
|