1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
|
<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>
|