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