tprint.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tprint.3 (9107B)
---
1 .TH PRINT 3
2 .SH NAME
3 print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .PP
7 .B #include <libc.h>
8 .PP
9 .ta \w'\fLchar* 'u
10 .B
11 int print(char *format, ...)
12 .PP
13 .B
14 int fprint(int fd, char *format, ...)
15 .PP
16 .B
17 int sprint(char *s, char *format, ...)
18 .PP
19 .B
20 int snprint(char *s, int len, char *format, ...)
21 .PP
22 .B
23 char* seprint(char *s, char *e, char *format, ...)
24 .PP
25 .B
26 char* smprint(char *format, ...)
27 .PP
28 .B
29 int runesprint(Rune *s, char *format, ...)
30 .PP
31 .B
32 int runesnprint(Rune *s, int len, char *format, ...)
33 .PP
34 .B
35 Rune* runeseprint(Rune *s, Rune *e, char *format, ...)
36 .PP
37 .B
38 Rune* runesmprint(char *format, ...)
39 .PP
40 .B
41 int vfprint(int fd, char *format, va_list v)
42 .PP
43 .B
44 int vsnprint(char *s, int len, char *format, va_list v)
45 .PP
46 .B
47 char* vseprint(char *s, char *e, char *format, va_list v)
48 .PP
49 .B
50 char* vsmprint(char *format, va_list v)
51 .PP
52 .B
53 int runevsnprint(Rune *s, int len, char *format, va_list v)
54 .PP
55 .B
56 Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v)
57 .PP
58 .B
59 Rune* runevsmprint(Rune *format, va_list v)
60 .PP
61 .B
62 .SH DESCRIPTION
63 .I Print
64 writes text to the standard output.
65 .I Fprint
66 writes to the named output
67 file descriptor:
68 a buffered form
69 is described in
70 .MR bio (3) .
71 .I Sprint
72 places text
73 followed by the NUL character
74 .RB ( \e0 )
75 in consecutive bytes starting at
76 .IR s ;
77 it is the user's responsibility to ensure that
78 enough storage is available.
79 Each function returns the number of bytes
80 transmitted (not including the NUL
81 in the case of
82 .IR sprint ),
83 or
84 a negative value if an output error was encountered.
85 .PP
86 .I Snprint
87 is like
88 .IR sprint ,
89 but will not place more than
90 .I len
91 bytes in
92 .IR s .
93 Its result is always NUL-terminated and holds the maximal
94 number of complete UTF-8 characters that can fit.
95 .I Seprint
96 is like
97 .IR snprint ,
98 except that the end is indicated by a pointer
99 .I e
100 rather than a count and the return value points to the terminating NUL of the
101 resulting string.
102 .I Smprint
103 is like
104 .IR sprint ,
105 except that it prints into and returns a string of the required length, which is
106 allocated by
107 .MR malloc (3) .
108 .PP
109 The routines
110 .IR runesprint ,
111 .IR runesnprint ,
112 .IR runeseprint ,
113 and
114 .I runesmprint
115 are the same as
116 .IR sprint ,
117 .IR snprint ,
118 .IR seprint
119 and
120 .I smprint
121 except that their output is rune strings instead of byte strings.
122 They return a rune count rather than a byte count.
123 .PP
124 Finally, the routines
125 .IR vfprint ,
126 .IR vsnprint ,
127 .IR vseprint ,
128 .IR vsmprint ,
129 .IR runevsnprint ,
130 .IR runevseprint ,
131 and
132 .I runevsmprint
133 are like their
134 .BR v-less
135 relatives except they take as arguments a
136 .B va_list
137 parameter, so they can be called within a variadic function.
138 The Example section shows a representative usage.
139 .PP
140 Each of these functions
141 converts, formats, and prints its
142 trailing arguments
143 under control of a
144 .IR format
145 string.
146 The
147 format
148 contains two types of objects:
149 plain characters, which are simply copied to the
150 output stream,
151 and conversion specifications,
152 each of which results in fetching of
153 zero or more
154 arguments.
155 The results are undefined if there are arguments of the
156 wrong type or too few
157 arguments for the format.
158 If the format is exhausted while
159 arguments remain, the excess
160 is ignored.
161 .PP
162 Each conversion specification has the following format:
163 .IP
164 .B "% [flags] verb
165 .PP
166 The verb is a single character and each flag is a single character or a
167 (decimal) numeric string.
168 Up to two numeric strings may be used;
169 the first is called
170 .IR width ,
171 the second
172 .IR precision .
173 A period can be used to separate them, and if the period is
174 present then
175 .I width
176 and
177 .I precision
178 are taken to be zero if missing, otherwise they are `omitted'.
179 Either or both of the numbers may be replaced with the character
180 .BR * ,
181 meaning that the actual number will be obtained from the argument list
182 as an integer.
183 The flags and numbers are arguments to
184 the
185 .I verb
186 described below.
187 .PP
188 The numeric verbs
189 .BR d ,
190 .BR o ,
191 .BR b ,
192 .BR x ,
193 and
194 .B X
195 format their arguments in decimal,
196 octal, binary, hexadecimal, and upper case hexadecimal.
197 Each interprets the flags
198 .BR 0 ,
199 .BR h ,
200 .BR hh ,
201 .BR l ,
202 .BR u ,
203 .BR + ,
204 .BR - ,
205 .BR , ,
206 and
207 .B #
208 to mean pad with zeros,
209 short, byte, long, unsigned, always print a sign, left justified, commas every three digits,
210 and alternate format.
211 Also, a space character in the flag
212 position is like
213 .BR + ,
214 but prints a space instead of a plus sign for non-negative values.
215 If neither
216 short nor long is specified,
217 then the argument is an
218 .BR int .
219 If unsigned is specified,
220 then the argument is interpreted as a
221 positive number and no sign is output.
222 If two
223 .B l
224 flags are given,
225 then the argument is interpreted as a
226 .B vlong
227 (usually an 8-byte, sometimes a 4-byte integer).
228 If
229 .I precision
230 is not omitted, the number is padded on the left with zeros
231 until at least
232 .I precision
233 digits appear.
234 If
235 .I precision
236 is explicitly 0, and the number is 0,
237 no digits are generated, and alternate formatting
238 does not apply.
239 Then, if alternate format is specified,
240 for
241 .B o
242 conversion, the number is preceded by a
243 .B 0
244 if it doesn't already begin with one;
245 for
246 .B x
247 conversion, the number is preceded by
248 .BR 0x ;
249 for
250 .B X
251 conversion, the number is preceded by
252 .BR 0X .
253 Finally, if
254 .I width
255 is not omitted, the number is padded on the left (or right, if
256 left justification is specified) with enough blanks to
257 make the field at least
258 .I width
259 characters long.
260 .PP
261 The floating point verbs
262 .BR f ,
263 .BR e ,
264 .BR E ,
265 .BR g ,
266 and
267 .B G
268 take a
269 .B double
270 argument.
271 Each interprets the flags
272 .BR 0 ,
273 .BR L
274 .BR + ,
275 .BR - ,
276 and
277 .B #
278 to mean pad with zeros,
279 long double argument,
280 always print a sign,
281 left justified,
282 and
283 alternate format.
284 .I Width
285 is the minimum field width and,
286 if the converted value takes up less than
287 .I width
288 characters, it is padded on the left (or right, if `left justified')
289 with spaces.
290 .I Precision
291 is the number of digits that are converted after the decimal place for
292 .BR e ,
293 .BR E ,
294 and
295 .B f
296 conversions,
297 and
298 .I precision
299 is the maximum number of significant digits for
300 .B g
301 and
302 .B G
303 conversions.
304 The
305 .B f
306 verb produces output of the form
307 .RB [ - ] digits [ .digits\fR].
308 .B E
309 conversion appends an exponent
310 .BR E [ - ] digits ,
311 and
312 .B e
313 conversion appends an exponent
314 .BR e [ - ] digits .
315 The
316 .B g
317 verb will output the argument in either
318 .B e
319 or
320 .B f
321 with the goal of producing the smallest output.
322 Also, trailing zeros are omitted from the fraction part of
323 the output, and a trailing decimal point appears only if it is followed
324 by a digit.
325 The
326 .B G
327 verb is similar, but uses
328 .B E
329 format instead of
330 .BR e .
331 When alternate format is specified, the result will always contain a decimal point,
332 and for
333 .B g
334 and
335 .B G
336 conversions, trailing zeros are not removed.
337 .PP
338 The
339 .B s
340 verb copies a NUL-terminated string
341 (pointer to
342 .BR char )
343 to the output.
344 The number of characters copied
345 .RI ( n )
346 is the minimum
347 of the size of the string and
348 .IR precision .
349 These
350 .I n
351 characters are justified within a field of
352 .I width
353 characters as described above.
354 If a
355 .I precision
356 is given, it is safe for the string not to be nul-terminated
357 as long as it is at least
358 .I precision
359 characters (not bytes!) long.
360 The
361 .B S
362 verb is similar, but it interprets its pointer as an array
363 of runes (see
364 .MR utf (7) );
365 the runes are converted to
366 .SM UTF
367 before output.
368 .PP
369 The
370 .B c
371 verb copies a single
372 .B char
373 (promoted to
374 .BR int )
375 justified within a field of
376 .I width
377 characters as described above.
378 The
379 .B C
380 verb is similar, but works on runes.
381 .PP
382 The
383 .B p
384 verb formats a pointer value.
385 At the moment, it is a synonym for
386 .BR x ,
387 but that will change if pointers and integers are different sizes.
388 .PP
389 The
390 .B r
391 verb takes no arguments; it copies the error string returned by a call to
392 .MR errstr (3) .
393 .PP
394 Custom verbs may be installed using
395 .MR fmtinstall (3) .
396 .SH EXAMPLE
397 This function prints an error message with a variable
398 number of arguments and then quits.
399 .IP
400 .EX
401 .ta 6n +6n +6n
402 void fatal(char *msg, ...)
403 {
404 char buf[1024], *out;
405 va_list arg;
406
407 out = seprint(buf, buf+sizeof buf, "Fatal error: ");
408 va_start(arg, msg);
409 out = vseprint(out, buf+sizeof buf, msg, arg);
410 va_end(arg);
411 write(2, buf, out-buf);
412 exits("fatal error");
413 }
414 .EE
415 .SH SOURCE
416 .B \*9/src/lib9/fmt
417 .SH SEE ALSO
418 .MR fmtinstall (3) ,
419 .MR fprintf (3) ,
420 .MR utf (7)
421 .SH DIAGNOSTICS
422 Routines that write to a file descriptor or call
423 .IR malloc
424 set
425 .IR errstr .
426 .SH BUGS
427 The formatting is close to that specified for ANSI
428 .MR fprintf (3) ;
429 the main difference is that
430 .B b
431 and
432 .B r
433 are not in ANSI and
434 .B u
435 is a flag here instead of a verb.
436 Also, and distinctly not a bug,
437 .I print
438 and friends generate
439 .SM UTF
440 rather than
441 .SM ASCII.
442 .PP
443 There is no
444 .IR runeprint ,
445 .IR runefprint ,
446 etc. because runes are byte-order dependent and should not be written directly to a file; use the
447 UTF output of
448 .I print
449 or
450 .I fprint
451 instead.
452 Also,
453 .I sprint
454 is deprecated for safety reasons; use
455 .IR snprint ,
456 .IR seprint ,
457 or
458 .I smprint
459 instead.
460 Safety also precludes the existence of
461 .IR runesprint .