1 b2cfc4e2 2003-09-30 devnull .TH PRINT 3
3 058b0118 2005-01-03 devnull print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output
4 b2cfc4e2 2003-09-30 devnull .SH SYNOPSIS
5 c8b6342d 2005-01-13 devnull .B #include <u.h>
7 c8b6342d 2005-01-13 devnull .B #include <libc.h>
9 b2cfc4e2 2003-09-30 devnull .ta \w'\fLchar* 'u
11 b2cfc4e2 2003-09-30 devnull int print(char *format, ...)
14 b2cfc4e2 2003-09-30 devnull int fprint(int fd, char *format, ...)
17 b2cfc4e2 2003-09-30 devnull int sprint(char *s, char *format, ...)
20 b2cfc4e2 2003-09-30 devnull int snprint(char *s, int len, char *format, ...)
23 b2cfc4e2 2003-09-30 devnull char* seprint(char *s, char *e, char *format, ...)
26 b2cfc4e2 2003-09-30 devnull char* smprint(char *format, ...)
29 b2cfc4e2 2003-09-30 devnull int runesprint(Rune *s, char *format, ...)
32 b2cfc4e2 2003-09-30 devnull int runesnprint(Rune *s, int len, char *format, ...)
35 b2cfc4e2 2003-09-30 devnull Rune* runeseprint(Rune *s, Rune *e, char *format, ...)
38 b2cfc4e2 2003-09-30 devnull Rune* runesmprint(char *format, ...)
41 b2cfc4e2 2003-09-30 devnull int vfprint(int fd, char *format, va_list v)
44 b2cfc4e2 2003-09-30 devnull int vsnprint(char *s, int len, char *format, va_list v)
47 b2cfc4e2 2003-09-30 devnull char* vseprint(char *s, char *e, char *format, va_list v)
50 b2cfc4e2 2003-09-30 devnull char* vsmprint(char *format, va_list v)
53 b2cfc4e2 2003-09-30 devnull int runevsnprint(Rune *s, int len, char *format, va_list v)
56 b2cfc4e2 2003-09-30 devnull Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v)
59 b2cfc4e2 2003-09-30 devnull Rune* runevsmprint(Rune *format, va_list v)
62 b2cfc4e2 2003-09-30 devnull .SH DESCRIPTION
64 b2cfc4e2 2003-09-30 devnull writes text to the standard output.
65 b2cfc4e2 2003-09-30 devnull .I Fprint
66 b2cfc4e2 2003-09-30 devnull writes to the named output
67 c8b6342d 2005-01-13 devnull file descriptor:
68 c8b6342d 2005-01-13 devnull a buffered form
69 c8b6342d 2005-01-13 devnull is described in
70 c8b6342d 2005-01-13 devnull .IR bio (3).
71 b2cfc4e2 2003-09-30 devnull .I Sprint
72 b2cfc4e2 2003-09-30 devnull places text
73 b2cfc4e2 2003-09-30 devnull followed by the NUL character
74 b2cfc4e2 2003-09-30 devnull .RB ( \e0 )
75 b2cfc4e2 2003-09-30 devnull in consecutive bytes starting at
77 b2cfc4e2 2003-09-30 devnull it is the user's responsibility to ensure that
78 b2cfc4e2 2003-09-30 devnull enough storage is available.
79 b2cfc4e2 2003-09-30 devnull Each function returns the number of bytes
80 b2cfc4e2 2003-09-30 devnull transmitted (not including the NUL
81 b2cfc4e2 2003-09-30 devnull in the case of
82 b2cfc4e2 2003-09-30 devnull .IR sprint ),
84 b2cfc4e2 2003-09-30 devnull a negative value if an output error was encountered.
86 b2cfc4e2 2003-09-30 devnull .I Snprint
88 b2cfc4e2 2003-09-30 devnull .IR sprint ,
89 b2cfc4e2 2003-09-30 devnull but will not place more than
93 b2cfc4e2 2003-09-30 devnull Its result is always NUL-terminated and holds the maximal
94 c8b6342d 2005-01-13 devnull number of complete UTF-8 characters that can fit.
95 b2cfc4e2 2003-09-30 devnull .I Seprint
97 b2cfc4e2 2003-09-30 devnull .IR snprint ,
98 b2cfc4e2 2003-09-30 devnull except that the end is indicated by a pointer
100 b2cfc4e2 2003-09-30 devnull rather than a count and the return value points to the terminating NUL of the
101 b2cfc4e2 2003-09-30 devnull resulting string.
102 b2cfc4e2 2003-09-30 devnull .I Smprint
104 b2cfc4e2 2003-09-30 devnull .IR sprint ,
105 b2cfc4e2 2003-09-30 devnull except that it prints into and returns a string of the required length, which is
106 b2cfc4e2 2003-09-30 devnull allocated by
107 b2cfc4e2 2003-09-30 devnull .IR malloc (3).
109 b2cfc4e2 2003-09-30 devnull The routines
110 b2cfc4e2 2003-09-30 devnull .IR runesprint ,
111 b2cfc4e2 2003-09-30 devnull .IR runesnprint ,
112 b2cfc4e2 2003-09-30 devnull .IR runeseprint ,
114 b2cfc4e2 2003-09-30 devnull .I runesmprint
115 b2cfc4e2 2003-09-30 devnull are the same as
116 b2cfc4e2 2003-09-30 devnull .IR sprint ,
117 b2cfc4e2 2003-09-30 devnull .IR snprint ,
118 b2cfc4e2 2003-09-30 devnull .IR seprint
120 b2cfc4e2 2003-09-30 devnull .I smprint
121 b2cfc4e2 2003-09-30 devnull except that their output is rune strings instead of byte strings.
123 b2cfc4e2 2003-09-30 devnull Finally, the routines
124 b2cfc4e2 2003-09-30 devnull .IR vfprint ,
125 b2cfc4e2 2003-09-30 devnull .IR vsnprint ,
126 b2cfc4e2 2003-09-30 devnull .IR vseprint ,
127 b2cfc4e2 2003-09-30 devnull .IR vsmprint ,
128 b2cfc4e2 2003-09-30 devnull .IR runevsnprint ,
129 b2cfc4e2 2003-09-30 devnull .IR runevseprint ,
131 b2cfc4e2 2003-09-30 devnull .I runevsmprint
132 b2cfc4e2 2003-09-30 devnull are like their
133 b2cfc4e2 2003-09-30 devnull .BR v-less
134 b2cfc4e2 2003-09-30 devnull relatives except they take as arguments a
135 b2cfc4e2 2003-09-30 devnull .B va_list
136 b2cfc4e2 2003-09-30 devnull parameter, so they can be called within a variadic function.
137 b2cfc4e2 2003-09-30 devnull The Example section shows a representative usage.
139 b2cfc4e2 2003-09-30 devnull Each of these functions
140 b2cfc4e2 2003-09-30 devnull converts, formats, and prints its
141 b2cfc4e2 2003-09-30 devnull trailing arguments
142 b2cfc4e2 2003-09-30 devnull under control of a
143 b2cfc4e2 2003-09-30 devnull .IR format
147 b2cfc4e2 2003-09-30 devnull contains two types of objects:
148 b2cfc4e2 2003-09-30 devnull plain characters, which are simply copied to the
149 b2cfc4e2 2003-09-30 devnull output stream,
150 b2cfc4e2 2003-09-30 devnull and conversion specifications,
151 b2cfc4e2 2003-09-30 devnull each of which results in fetching of
152 b2cfc4e2 2003-09-30 devnull zero or more
153 b2cfc4e2 2003-09-30 devnull arguments.
154 b2cfc4e2 2003-09-30 devnull The results are undefined if there are arguments of the
155 b2cfc4e2 2003-09-30 devnull wrong type or too few
156 b2cfc4e2 2003-09-30 devnull arguments for the format.
157 b2cfc4e2 2003-09-30 devnull If the format is exhausted while
158 b2cfc4e2 2003-09-30 devnull arguments remain, the excess
159 b2cfc4e2 2003-09-30 devnull is ignored.
161 b2cfc4e2 2003-09-30 devnull Each conversion specification has the following format:
163 b2cfc4e2 2003-09-30 devnull .B "% [flags] verb
165 b2cfc4e2 2003-09-30 devnull The verb is a single character and each flag is a single character or a
166 b2cfc4e2 2003-09-30 devnull (decimal) numeric string.
167 b2cfc4e2 2003-09-30 devnull Up to two numeric strings may be used;
168 b2cfc4e2 2003-09-30 devnull the first is called
169 b2cfc4e2 2003-09-30 devnull .IR width ,
170 b2cfc4e2 2003-09-30 devnull the second
171 b2cfc4e2 2003-09-30 devnull .IR precision .
172 b2cfc4e2 2003-09-30 devnull A period can be used to separate them, and if the period is
173 b2cfc4e2 2003-09-30 devnull present then
174 b2cfc4e2 2003-09-30 devnull .I width
176 b2cfc4e2 2003-09-30 devnull .I precision
177 b2cfc4e2 2003-09-30 devnull are taken to be zero if missing, otherwise they are `omitted'.
178 b2cfc4e2 2003-09-30 devnull Either or both of the numbers may be replaced with the character
180 b2cfc4e2 2003-09-30 devnull meaning that the actual number will be obtained from the argument list
181 b2cfc4e2 2003-09-30 devnull as an integer.
182 b2cfc4e2 2003-09-30 devnull The flags and numbers are arguments to
185 b2cfc4e2 2003-09-30 devnull described below.
187 b2cfc4e2 2003-09-30 devnull The numeric verbs
194 c8b6342d 2005-01-13 devnull format their arguments in decimal,
195 c8b6342d 2005-01-13 devnull octal, binary, hexadecimal, and upper case hexadecimal.
196 b2cfc4e2 2003-09-30 devnull Each interprets the flags
199 b2cfc4e2 2003-09-30 devnull .BR hh ,
207 b2cfc4e2 2003-09-30 devnull to mean pad with zeros,
208 c8b6342d 2005-01-13 devnull short, byte, long, unsigned, always print a sign, left justified, commas every three digits,
209 b2cfc4e2 2003-09-30 devnull and alternate format.
210 b2cfc4e2 2003-09-30 devnull Also, a space character in the flag
211 b2cfc4e2 2003-09-30 devnull position is like
213 b2cfc4e2 2003-09-30 devnull but prints a space instead of a plus sign for non-negative values.
214 b2cfc4e2 2003-09-30 devnull If neither
215 b2cfc4e2 2003-09-30 devnull short nor long is specified,
216 b2cfc4e2 2003-09-30 devnull then the argument is an
217 b2cfc4e2 2003-09-30 devnull .BR int .
218 c8b6342d 2005-01-13 devnull If unsigned is specified,
219 b2cfc4e2 2003-09-30 devnull then the argument is interpreted as a
220 c8b6342d 2005-01-13 devnull positive number and no sign is output.
223 b2cfc4e2 2003-09-30 devnull flags are given,
224 b2cfc4e2 2003-09-30 devnull then the argument is interpreted as a
225 b2cfc4e2 2003-09-30 devnull .B vlong
226 b2cfc4e2 2003-09-30 devnull (usually an 8-byte, sometimes a 4-byte integer).
228 b2cfc4e2 2003-09-30 devnull .I precision
229 b2cfc4e2 2003-09-30 devnull is not omitted, the number is padded on the left with zeros
230 b2cfc4e2 2003-09-30 devnull until at least
231 b2cfc4e2 2003-09-30 devnull .I precision
232 b2cfc4e2 2003-09-30 devnull digits appear.
234 b2cfc4e2 2003-09-30 devnull .I precision
235 b2cfc4e2 2003-09-30 devnull is explicitly 0, and the number is 0,
236 b2cfc4e2 2003-09-30 devnull no digits are generated, and alternate formatting
237 b2cfc4e2 2003-09-30 devnull does not apply.
238 b2cfc4e2 2003-09-30 devnull Then, if alternate format is specified,
241 b2cfc4e2 2003-09-30 devnull conversion, the number is preceded by a
243 c8b6342d 2005-01-13 devnull if it doesn't already begin with one;
246 b2cfc4e2 2003-09-30 devnull conversion, the number is preceded by
247 b2cfc4e2 2003-09-30 devnull .BR 0x ;
250 b2cfc4e2 2003-09-30 devnull conversion, the number is preceded by
251 b2cfc4e2 2003-09-30 devnull .BR 0X .
252 b2cfc4e2 2003-09-30 devnull Finally, if
253 b2cfc4e2 2003-09-30 devnull .I width
254 b2cfc4e2 2003-09-30 devnull is not omitted, the number is padded on the left (or right, if
255 b2cfc4e2 2003-09-30 devnull left justification is specified) with enough blanks to
256 b2cfc4e2 2003-09-30 devnull make the field at least
257 b2cfc4e2 2003-09-30 devnull .I width
258 b2cfc4e2 2003-09-30 devnull characters long.
260 b2cfc4e2 2003-09-30 devnull The floating point verbs
268 b2cfc4e2 2003-09-30 devnull .B double
269 b2cfc4e2 2003-09-30 devnull argument.
270 b2cfc4e2 2003-09-30 devnull Each interprets the flags
277 b2cfc4e2 2003-09-30 devnull to mean pad with zeros,
278 b2cfc4e2 2003-09-30 devnull long double argument,
279 b2cfc4e2 2003-09-30 devnull always print a sign,
280 b2cfc4e2 2003-09-30 devnull left justified,
282 b2cfc4e2 2003-09-30 devnull alternate format.
283 b2cfc4e2 2003-09-30 devnull .I Width
284 b2cfc4e2 2003-09-30 devnull is the minimum field width and,
285 b2cfc4e2 2003-09-30 devnull if the converted value takes up less than
286 b2cfc4e2 2003-09-30 devnull .I width
287 b2cfc4e2 2003-09-30 devnull characters, it is padded on the left (or right, if `left justified')
288 b2cfc4e2 2003-09-30 devnull with spaces.
289 b2cfc4e2 2003-09-30 devnull .I Precision
290 b2cfc4e2 2003-09-30 devnull is the number of digits that are converted after the decimal place for
295 b2cfc4e2 2003-09-30 devnull conversions,
297 b2cfc4e2 2003-09-30 devnull .I precision
298 b2cfc4e2 2003-09-30 devnull is the maximum number of significant digits for
302 b2cfc4e2 2003-09-30 devnull conversions.
305 b2cfc4e2 2003-09-30 devnull verb produces output of the form
306 b2cfc4e2 2003-09-30 devnull .RB [ - ] digits [ .digits\fR].
308 b2cfc4e2 2003-09-30 devnull conversion appends an exponent
309 b2cfc4e2 2003-09-30 devnull .BR E [ - ] digits ,
312 b2cfc4e2 2003-09-30 devnull conversion appends an exponent
313 b2cfc4e2 2003-09-30 devnull .BR e [ - ] digits .
316 b2cfc4e2 2003-09-30 devnull verb will output the argument in either
320 b2cfc4e2 2003-09-30 devnull with the goal of producing the smallest output.
321 b2cfc4e2 2003-09-30 devnull Also, trailing zeros are omitted from the fraction part of
322 b2cfc4e2 2003-09-30 devnull the output, and a trailing decimal point appears only if it is followed
323 b2cfc4e2 2003-09-30 devnull by a digit.
326 b2cfc4e2 2003-09-30 devnull verb is similar, but uses
328 b2cfc4e2 2003-09-30 devnull format instead of
330 b2cfc4e2 2003-09-30 devnull When alternate format is specified, the result will always contain a decimal point,
335 b2cfc4e2 2003-09-30 devnull conversions, trailing zeros are not removed.
339 c8b6342d 2005-01-13 devnull verb copies a NUL-terminated string
340 b2cfc4e2 2003-09-30 devnull (pointer to
341 b2cfc4e2 2003-09-30 devnull .BR char )
342 b2cfc4e2 2003-09-30 devnull to the output.
343 b2cfc4e2 2003-09-30 devnull The number of characters copied
344 b2cfc4e2 2003-09-30 devnull .RI ( n )
345 b2cfc4e2 2003-09-30 devnull is the minimum
346 b2cfc4e2 2003-09-30 devnull of the size of the string and
347 b2cfc4e2 2003-09-30 devnull .IR precision .
350 b2cfc4e2 2003-09-30 devnull characters are justified within a field of
351 b2cfc4e2 2003-09-30 devnull .I width
352 b2cfc4e2 2003-09-30 devnull characters as described above.
354 b2cfc4e2 2003-09-30 devnull .I precision
355 b2cfc4e2 2003-09-30 devnull is given, it is safe for the string not to be nul-terminated
356 b2cfc4e2 2003-09-30 devnull as long as it is at least
357 b2cfc4e2 2003-09-30 devnull .I precision
358 b2cfc4e2 2003-09-30 devnull characters (not bytes!) long.
361 b2cfc4e2 2003-09-30 devnull verb is similar, but it interprets its pointer as an array
362 b2cfc4e2 2003-09-30 devnull of runes (see
363 b2cfc4e2 2003-09-30 devnull .IR utf (7));
364 b2cfc4e2 2003-09-30 devnull the runes are converted to
366 b2cfc4e2 2003-09-30 devnull before output.
370 b2cfc4e2 2003-09-30 devnull verb copies a single
372 b2cfc4e2 2003-09-30 devnull (promoted to
373 b2cfc4e2 2003-09-30 devnull .BR int )
374 b2cfc4e2 2003-09-30 devnull justified within a field of
375 b2cfc4e2 2003-09-30 devnull .I width
376 b2cfc4e2 2003-09-30 devnull characters as described above.
379 b2cfc4e2 2003-09-30 devnull verb is similar, but works on runes.
383 b2cfc4e2 2003-09-30 devnull verb formats a pointer value.
384 b2cfc4e2 2003-09-30 devnull At the moment, it is a synonym for
386 b2cfc4e2 2003-09-30 devnull but that will change if pointers and integers are different sizes.
390 b2cfc4e2 2003-09-30 devnull verb takes no arguments; it copies the error string returned by a call to
391 c8b6342d 2005-01-13 devnull .IR errstr (3).
393 b2cfc4e2 2003-09-30 devnull Custom verbs may be installed using
394 b2cfc4e2 2003-09-30 devnull .IR fmtinstall (3).
395 b2cfc4e2 2003-09-30 devnull .SH EXAMPLE
396 b2cfc4e2 2003-09-30 devnull This function prints an error message with a variable
397 b2cfc4e2 2003-09-30 devnull number of arguments and then quits.
400 b2cfc4e2 2003-09-30 devnull .ta 6n +6n +6n
401 b2cfc4e2 2003-09-30 devnull void fatal(char *msg, ...)
403 b2cfc4e2 2003-09-30 devnull char buf[1024], *out;
404 b2cfc4e2 2003-09-30 devnull va_list arg;
406 c8b6342d 2005-01-13 devnull out = seprint(buf, buf+sizeof buf, "Fatal error: ");
407 b2cfc4e2 2003-09-30 devnull va_start(arg, msg);
408 b2cfc4e2 2003-09-30 devnull out = vseprint(out, buf+sizeof buf, msg, arg);
409 b2cfc4e2 2003-09-30 devnull va_end(arg);
410 b2cfc4e2 2003-09-30 devnull write(2, buf, out-buf);
411 c8b6342d 2005-01-13 devnull exits("fatal error");
414 93aa30a8 2005-01-14 devnull .SH SOURCE
415 adc93f60 2005-01-14 devnull .B \*9/src/lib9/fmt
416 b2cfc4e2 2003-09-30 devnull .SH SEE ALSO
417 b2cfc4e2 2003-09-30 devnull .IR fmtinstall (3),
418 b2cfc4e2 2003-09-30 devnull .IR fprintf (3),
419 b2cfc4e2 2003-09-30 devnull .IR utf (7)
420 b2cfc4e2 2003-09-30 devnull .SH DIAGNOSTICS
421 b2cfc4e2 2003-09-30 devnull Routines that write to a file descriptor or call
422 b2cfc4e2 2003-09-30 devnull .IR malloc
424 b2cfc4e2 2003-09-30 devnull .IR errstr .
425 b2cfc4e2 2003-09-30 devnull .SH BUGS
426 b2cfc4e2 2003-09-30 devnull The formatting is close to that specified for ANSI
427 b2cfc4e2 2003-09-30 devnull .IR fprintf (3);
428 b2cfc4e2 2003-09-30 devnull the main difference is that
432 c8b6342d 2005-01-13 devnull are not in ANSI and
434 c8b6342d 2005-01-13 devnull is a flag here instead of a verb.
435 b2cfc4e2 2003-09-30 devnull Also, and distinctly not a bug,
436 b2cfc4e2 2003-09-30 devnull .I print
437 b2cfc4e2 2003-09-30 devnull and friends generate
439 b2cfc4e2 2003-09-30 devnull rather than
440 b2cfc4e2 2003-09-30 devnull .SM ASCII.
442 b2cfc4e2 2003-09-30 devnull There is no
443 c8b6342d 2005-01-13 devnull .IR runeprint ,
444 c8b6342d 2005-01-13 devnull .IR runefprint ,
445 b2cfc4e2 2003-09-30 devnull etc. because runes are byte-order dependent and should not be written directly to a file; use the
446 b2cfc4e2 2003-09-30 devnull UTF output of
447 b2cfc4e2 2003-09-30 devnull .I print
449 b2cfc4e2 2003-09-30 devnull .I fprint
450 b2cfc4e2 2003-09-30 devnull instead.
452 b2cfc4e2 2003-09-30 devnull .I sprint
453 b2cfc4e2 2003-09-30 devnull is deprecated for safety reasons; use
454 b2cfc4e2 2003-09-30 devnull .IR snprint ,
455 b2cfc4e2 2003-09-30 devnull .IR seprint ,
457 b2cfc4e2 2003-09-30 devnull .I smprint
458 b2cfc4e2 2003-09-30 devnull instead.
459 b2cfc4e2 2003-09-30 devnull Safety also precludes the existence of
460 b2cfc4e2 2003-09-30 devnull .IR runesprint .
