Blob


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 .IR 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 .IR 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 .PP
123 Finally, the routines
124 .IR vfprint ,
125 .IR vsnprint ,
126 .IR vseprint ,
127 .IR vsmprint ,
128 .IR runevsnprint ,
129 .IR runevseprint ,
130 and
131 .I runevsmprint
132 are like their
133 .BR v-less
134 relatives except they take as arguments a
135 .B va_list
136 parameter, so they can be called within a variadic function.
137 The Example section shows a representative usage.
138 .PP
139 Each of these functions
140 converts, formats, and prints its
141 trailing arguments
142 under control of a
143 .IR format
144 string.
145 The
146 format
147 contains two types of objects:
148 plain characters, which are simply copied to the
149 output stream,
150 and conversion specifications,
151 each of which results in fetching of
152 zero or more
153 arguments.
154 The results are undefined if there are arguments of the
155 wrong type or too few
156 arguments for the format.
157 If the format is exhausted while
158 arguments remain, the excess
159 is ignored.
160 .PP
161 Each conversion specification has the following format:
162 .IP
163 .B "% [flags] verb
164 .PP
165 The verb is a single character and each flag is a single character or a
166 (decimal) numeric string.
167 Up to two numeric strings may be used;
168 the first is called
169 .IR width ,
170 the second
171 .IR precision .
172 A period can be used to separate them, and if the period is
173 present then
174 .I width
175 and
176 .I precision
177 are taken to be zero if missing, otherwise they are `omitted'.
178 Either or both of the numbers may be replaced with the character
179 .BR * ,
180 meaning that the actual number will be obtained from the argument list
181 as an integer.
182 The flags and numbers are arguments to
183 the
184 .I verb
185 described below.
186 .PP
187 The numeric verbs
188 .BR d ,
189 .BR o ,
190 .BR b ,
191 .BR x ,
192 and
193 .B X
194 format their arguments in decimal,
195 octal, binary, hexadecimal, and upper case hexadecimal.
196 Each interprets the flags
197 .BR 0 ,
198 .BR h ,
199 .BR hh ,
200 .BR l ,
201 .BR u ,
202 .BR + ,
203 .BR - ,
204 .BR , ,
205 and
206 .B #
207 to mean pad with zeros,
208 short, byte, long, unsigned, always print a sign, left justified, commas every three digits,
209 and alternate format.
210 Also, a space character in the flag
211 position is like
212 .BR + ,
213 but prints a space instead of a plus sign for non-negative values.
214 If neither
215 short nor long is specified,
216 then the argument is an
217 .BR int .
218 If unsigned is specified,
219 then the argument is interpreted as a
220 positive number and no sign is output.
221 If two
222 .B l
223 flags are given,
224 then the argument is interpreted as a
225 .B vlong
226 (usually an 8-byte, sometimes a 4-byte integer).
227 If
228 .I precision
229 is not omitted, the number is padded on the left with zeros
230 until at least
231 .I precision
232 digits appear.
233 If
234 .I precision
235 is explicitly 0, and the number is 0,
236 no digits are generated, and alternate formatting
237 does not apply.
238 Then, if alternate format is specified,
239 for
240 .B o
241 conversion, the number is preceded by a
242 .B 0
243 if it doesn't already begin with one;
244 for
245 .B x
246 conversion, the number is preceded by
247 .BR 0x ;
248 for
249 .B X
250 conversion, the number is preceded by
251 .BR 0X .
252 Finally, if
253 .I width
254 is not omitted, the number is padded on the left (or right, if
255 left justification is specified) with enough blanks to
256 make the field at least
257 .I width
258 characters long.
259 .PP
260 The floating point verbs
261 .BR f ,
262 .BR e ,
263 .BR E ,
264 .BR g ,
265 and
266 .B G
267 take a
268 .B double
269 argument.
270 Each interprets the flags
271 .BR 0 ,
272 .BR L
273 .BR + ,
274 .BR - ,
275 and
276 .B #
277 to mean pad with zeros,
278 long double argument,
279 always print a sign,
280 left justified,
281 and
282 alternate format.
283 .I Width
284 is the minimum field width and,
285 if the converted value takes up less than
286 .I width
287 characters, it is padded on the left (or right, if `left justified')
288 with spaces.
289 .I Precision
290 is the number of digits that are converted after the decimal place for
291 .BR e ,
292 .BR E ,
293 and
294 .B f
295 conversions,
296 and
297 .I precision
298 is the maximum number of significant digits for
299 .B g
300 and
301 .B G
302 conversions.
303 The
304 .B f
305 verb produces output of the form
306 .RB [ - ] digits [ .digits\fR].
307 .B E
308 conversion appends an exponent
309 .BR E [ - ] digits ,
310 and
311 .B e
312 conversion appends an exponent
313 .BR e [ - ] digits .
314 The
315 .B g
316 verb will output the argument in either
317 .B e
318 or
319 .B f
320 with the goal of producing the smallest output.
321 Also, trailing zeros are omitted from the fraction part of
322 the output, and a trailing decimal point appears only if it is followed
323 by a digit.
324 The
325 .B G
326 verb is similar, but uses
327 .B E
328 format instead of
329 .BR e .
330 When alternate format is specified, the result will always contain a decimal point,
331 and for
332 .B g
333 and
334 .B G
335 conversions, trailing zeros are not removed.
336 .PP
337 The
338 .B s
339 verb copies a NUL-terminated string
340 (pointer to
341 .BR char )
342 to the output.
343 The number of characters copied
344 .RI ( n )
345 is the minimum
346 of the size of the string and
347 .IR precision .
348 These
349 .I n
350 characters are justified within a field of
351 .I width
352 characters as described above.
353 If a
354 .I precision
355 is given, it is safe for the string not to be nul-terminated
356 as long as it is at least
357 .I precision
358 characters (not bytes!) long.
359 The
360 .B S
361 verb is similar, but it interprets its pointer as an array
362 of runes (see
363 .IR utf (7));
364 the runes are converted to
365 .SM UTF
366 before output.
367 .PP
368 The
369 .B c
370 verb copies a single
371 .B char
372 (promoted to
373 .BR int )
374 justified within a field of
375 .I width
376 characters as described above.
377 The
378 .B C
379 verb is similar, but works on runes.
380 .PP
381 The
382 .B p
383 verb formats a pointer value.
384 At the moment, it is a synonym for
385 .BR x ,
386 but that will change if pointers and integers are different sizes.
387 .PP
388 The
389 .B r
390 verb takes no arguments; it copies the error string returned by a call to
391 .IR errstr (3).
392 .PP
393 Custom verbs may be installed using
394 .IR fmtinstall (3).
395 .SH EXAMPLE
396 This function prints an error message with a variable
397 number of arguments and then quits.
398 .IP
399 .EX
400 .ta 6n +6n +6n
401 void fatal(char *msg, ...)
403 char buf[1024], *out;
404 va_list arg;
406 out = seprint(buf, buf+sizeof buf, "Fatal error: ");
407 va_start(arg, msg);
408 out = vseprint(out, buf+sizeof buf, msg, arg);
409 va_end(arg);
410 write(2, buf, out-buf);
411 exits("fatal error");
413 .EE
414 .SH SOURCE
415 .B \*9/src/lib9/fmt
416 .SH SEE ALSO
417 .IR fmtinstall (3),
418 .IR fprintf (3),
419 .IR utf (7)
420 .SH DIAGNOSTICS
421 Routines that write to a file descriptor or call
422 .IR malloc
423 set
424 .IR errstr .
425 .SH BUGS
426 The formatting is close to that specified for ANSI
427 .IR fprintf (3);
428 the main difference is that
429 .B b
430 and
431 .B r
432 are not in ANSI and
433 .B u
434 is a flag here instead of a verb.
435 Also, and distinctly not a bug,
436 .I print
437 and friends generate
438 .SM UTF
439 rather than
440 .SM ASCII.
441 .PP
442 There is no
443 .IR runeprint ,
444 .IR runefprint ,
445 etc. because runes are byte-order dependent and should not be written directly to a file; use the
446 UTF output of
447 .I print
448 or
449 .I fprint
450 instead.
451 Also,
452 .I sprint
453 is deprecated for safety reasons; use
454 .IR snprint ,
455 .IR seprint ,
456 or
457 .I smprint
458 instead.
459 Safety also precludes the existence of
460 .IR runesprint .