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 d32deab1 2020-08-16 rsc .MR 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 d32deab1 2020-08-16 rsc .MR 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.
122 38bb7c11 2006-07-02 devnull They return a rune count rather than a byte count.
124 b2cfc4e2 2003-09-30 devnull Finally, the routines
125 b2cfc4e2 2003-09-30 devnull .IR vfprint ,
126 b2cfc4e2 2003-09-30 devnull .IR vsnprint ,
127 b2cfc4e2 2003-09-30 devnull .IR vseprint ,
128 b2cfc4e2 2003-09-30 devnull .IR vsmprint ,
129 b2cfc4e2 2003-09-30 devnull .IR runevsnprint ,
130 b2cfc4e2 2003-09-30 devnull .IR runevseprint ,
132 b2cfc4e2 2003-09-30 devnull .I runevsmprint
133 b2cfc4e2 2003-09-30 devnull are like their
134 b2cfc4e2 2003-09-30 devnull .BR v-less
135 b2cfc4e2 2003-09-30 devnull relatives except they take as arguments a
136 b2cfc4e2 2003-09-30 devnull .B va_list
137 b2cfc4e2 2003-09-30 devnull parameter, so they can be called within a variadic function.
138 b2cfc4e2 2003-09-30 devnull The Example section shows a representative usage.
140 b2cfc4e2 2003-09-30 devnull Each of these functions
141 b2cfc4e2 2003-09-30 devnull converts, formats, and prints its
142 b2cfc4e2 2003-09-30 devnull trailing arguments
143 b2cfc4e2 2003-09-30 devnull under control of a
144 b2cfc4e2 2003-09-30 devnull .IR format
148 b2cfc4e2 2003-09-30 devnull contains two types of objects:
149 b2cfc4e2 2003-09-30 devnull plain characters, which are simply copied to the
150 b2cfc4e2 2003-09-30 devnull output stream,
151 b2cfc4e2 2003-09-30 devnull and conversion specifications,
152 b2cfc4e2 2003-09-30 devnull each of which results in fetching of
153 b2cfc4e2 2003-09-30 devnull zero or more
154 b2cfc4e2 2003-09-30 devnull arguments.
155 b2cfc4e2 2003-09-30 devnull The results are undefined if there are arguments of the
156 b2cfc4e2 2003-09-30 devnull wrong type or too few
157 b2cfc4e2 2003-09-30 devnull arguments for the format.
158 b2cfc4e2 2003-09-30 devnull If the format is exhausted while
159 b2cfc4e2 2003-09-30 devnull arguments remain, the excess
160 b2cfc4e2 2003-09-30 devnull is ignored.
162 b2cfc4e2 2003-09-30 devnull Each conversion specification has the following format:
164 b2cfc4e2 2003-09-30 devnull .B "% [flags] verb
166 b2cfc4e2 2003-09-30 devnull The verb is a single character and each flag is a single character or a
167 b2cfc4e2 2003-09-30 devnull (decimal) numeric string.
168 b2cfc4e2 2003-09-30 devnull Up to two numeric strings may be used;
169 b2cfc4e2 2003-09-30 devnull the first is called
170 b2cfc4e2 2003-09-30 devnull .IR width ,
171 b2cfc4e2 2003-09-30 devnull the second
172 b2cfc4e2 2003-09-30 devnull .IR precision .
173 b2cfc4e2 2003-09-30 devnull A period can be used to separate them, and if the period is
174 b2cfc4e2 2003-09-30 devnull present then
175 b2cfc4e2 2003-09-30 devnull .I width
177 b2cfc4e2 2003-09-30 devnull .I precision
178 b2cfc4e2 2003-09-30 devnull are taken to be zero if missing, otherwise they are `omitted'.
179 b2cfc4e2 2003-09-30 devnull Either or both of the numbers may be replaced with the character
181 b2cfc4e2 2003-09-30 devnull meaning that the actual number will be obtained from the argument list
182 b2cfc4e2 2003-09-30 devnull as an integer.
183 b2cfc4e2 2003-09-30 devnull The flags and numbers are arguments to
186 b2cfc4e2 2003-09-30 devnull described below.
188 b2cfc4e2 2003-09-30 devnull The numeric verbs
195 c8b6342d 2005-01-13 devnull format their arguments in decimal,
196 c8b6342d 2005-01-13 devnull octal, binary, hexadecimal, and upper case hexadecimal.
197 b2cfc4e2 2003-09-30 devnull Each interprets the flags
200 b2cfc4e2 2003-09-30 devnull .BR hh ,
208 b2cfc4e2 2003-09-30 devnull to mean pad with zeros,
209 c8b6342d 2005-01-13 devnull short, byte, long, unsigned, always print a sign, left justified, commas every three digits,
210 b2cfc4e2 2003-09-30 devnull and alternate format.
211 b2cfc4e2 2003-09-30 devnull Also, a space character in the flag
212 b2cfc4e2 2003-09-30 devnull position is like
214 b2cfc4e2 2003-09-30 devnull but prints a space instead of a plus sign for non-negative values.
215 b2cfc4e2 2003-09-30 devnull If neither
216 b2cfc4e2 2003-09-30 devnull short nor long is specified,
217 b2cfc4e2 2003-09-30 devnull then the argument is an
218 b2cfc4e2 2003-09-30 devnull .BR int .
219 c8b6342d 2005-01-13 devnull If unsigned is specified,
220 b2cfc4e2 2003-09-30 devnull then the argument is interpreted as a
221 c8b6342d 2005-01-13 devnull positive number and no sign is output.
224 b2cfc4e2 2003-09-30 devnull flags are given,
225 b2cfc4e2 2003-09-30 devnull then the argument is interpreted as a
226 b2cfc4e2 2003-09-30 devnull .B vlong
227 b2cfc4e2 2003-09-30 devnull (usually an 8-byte, sometimes a 4-byte integer).
229 b2cfc4e2 2003-09-30 devnull .I precision
230 b2cfc4e2 2003-09-30 devnull is not omitted, the number is padded on the left with zeros
231 b2cfc4e2 2003-09-30 devnull until at least
232 b2cfc4e2 2003-09-30 devnull .I precision
233 b2cfc4e2 2003-09-30 devnull digits appear.
235 b2cfc4e2 2003-09-30 devnull .I precision
236 b2cfc4e2 2003-09-30 devnull is explicitly 0, and the number is 0,
237 b2cfc4e2 2003-09-30 devnull no digits are generated, and alternate formatting
238 b2cfc4e2 2003-09-30 devnull does not apply.
239 b2cfc4e2 2003-09-30 devnull Then, if alternate format is specified,
242 b2cfc4e2 2003-09-30 devnull conversion, the number is preceded by a
244 c8b6342d 2005-01-13 devnull if it doesn't already begin with one;
247 b2cfc4e2 2003-09-30 devnull conversion, the number is preceded by
248 b2cfc4e2 2003-09-30 devnull .BR 0x ;
251 b2cfc4e2 2003-09-30 devnull conversion, the number is preceded by
252 b2cfc4e2 2003-09-30 devnull .BR 0X .
253 b2cfc4e2 2003-09-30 devnull Finally, if
254 b2cfc4e2 2003-09-30 devnull .I width
255 b2cfc4e2 2003-09-30 devnull is not omitted, the number is padded on the left (or right, if
256 b2cfc4e2 2003-09-30 devnull left justification is specified) with enough blanks to
257 b2cfc4e2 2003-09-30 devnull make the field at least
258 b2cfc4e2 2003-09-30 devnull .I width
259 b2cfc4e2 2003-09-30 devnull characters long.
261 b2cfc4e2 2003-09-30 devnull The floating point verbs
269 b2cfc4e2 2003-09-30 devnull .B double
270 b2cfc4e2 2003-09-30 devnull argument.
271 b2cfc4e2 2003-09-30 devnull Each interprets the flags
278 b2cfc4e2 2003-09-30 devnull to mean pad with zeros,
279 b2cfc4e2 2003-09-30 devnull long double argument,
280 b2cfc4e2 2003-09-30 devnull always print a sign,
281 b2cfc4e2 2003-09-30 devnull left justified,
283 b2cfc4e2 2003-09-30 devnull alternate format.
284 b2cfc4e2 2003-09-30 devnull .I Width
285 b2cfc4e2 2003-09-30 devnull is the minimum field width and,
286 b2cfc4e2 2003-09-30 devnull if the converted value takes up less than
287 b2cfc4e2 2003-09-30 devnull .I width
288 b2cfc4e2 2003-09-30 devnull characters, it is padded on the left (or right, if `left justified')
289 b2cfc4e2 2003-09-30 devnull with spaces.
290 b2cfc4e2 2003-09-30 devnull .I Precision
291 b2cfc4e2 2003-09-30 devnull is the number of digits that are converted after the decimal place for
296 b2cfc4e2 2003-09-30 devnull conversions,
298 b2cfc4e2 2003-09-30 devnull .I precision
299 b2cfc4e2 2003-09-30 devnull is the maximum number of significant digits for
303 b2cfc4e2 2003-09-30 devnull conversions.
306 b2cfc4e2 2003-09-30 devnull verb produces output of the form
307 b2cfc4e2 2003-09-30 devnull .RB [ - ] digits [ .digits\fR].
309 b2cfc4e2 2003-09-30 devnull conversion appends an exponent
310 b2cfc4e2 2003-09-30 devnull .BR E [ - ] digits ,
313 b2cfc4e2 2003-09-30 devnull conversion appends an exponent
314 b2cfc4e2 2003-09-30 devnull .BR e [ - ] digits .
317 b2cfc4e2 2003-09-30 devnull verb will output the argument in either
321 b2cfc4e2 2003-09-30 devnull with the goal of producing the smallest output.
322 b2cfc4e2 2003-09-30 devnull Also, trailing zeros are omitted from the fraction part of
323 b2cfc4e2 2003-09-30 devnull the output, and a trailing decimal point appears only if it is followed
324 b2cfc4e2 2003-09-30 devnull by a digit.
327 b2cfc4e2 2003-09-30 devnull verb is similar, but uses
329 b2cfc4e2 2003-09-30 devnull format instead of
331 b2cfc4e2 2003-09-30 devnull When alternate format is specified, the result will always contain a decimal point,
336 b2cfc4e2 2003-09-30 devnull conversions, trailing zeros are not removed.
340 c8b6342d 2005-01-13 devnull verb copies a NUL-terminated string
341 b2cfc4e2 2003-09-30 devnull (pointer to
342 b2cfc4e2 2003-09-30 devnull .BR char )
343 b2cfc4e2 2003-09-30 devnull to the output.
344 b2cfc4e2 2003-09-30 devnull The number of characters copied
345 b2cfc4e2 2003-09-30 devnull .RI ( n )
346 b2cfc4e2 2003-09-30 devnull is the minimum
347 b2cfc4e2 2003-09-30 devnull of the size of the string and
348 b2cfc4e2 2003-09-30 devnull .IR precision .
351 b2cfc4e2 2003-09-30 devnull characters are justified within a field of
352 b2cfc4e2 2003-09-30 devnull .I width
353 b2cfc4e2 2003-09-30 devnull characters as described above.
355 b2cfc4e2 2003-09-30 devnull .I precision
356 b2cfc4e2 2003-09-30 devnull is given, it is safe for the string not to be nul-terminated
357 b2cfc4e2 2003-09-30 devnull as long as it is at least
358 b2cfc4e2 2003-09-30 devnull .I precision
359 b2cfc4e2 2003-09-30 devnull characters (not bytes!) long.
362 b2cfc4e2 2003-09-30 devnull verb is similar, but it interprets its pointer as an array
363 b2cfc4e2 2003-09-30 devnull of runes (see
364 d32deab1 2020-08-16 rsc .MR utf (7) );
365 b2cfc4e2 2003-09-30 devnull the runes are converted to
367 b2cfc4e2 2003-09-30 devnull before output.
371 b2cfc4e2 2003-09-30 devnull verb copies a single
373 b2cfc4e2 2003-09-30 devnull (promoted to
374 b2cfc4e2 2003-09-30 devnull .BR int )
375 b2cfc4e2 2003-09-30 devnull justified within a field of
376 b2cfc4e2 2003-09-30 devnull .I width
377 b2cfc4e2 2003-09-30 devnull characters as described above.
380 b2cfc4e2 2003-09-30 devnull verb is similar, but works on runes.
384 b2cfc4e2 2003-09-30 devnull verb formats a pointer value.
385 b2cfc4e2 2003-09-30 devnull At the moment, it is a synonym for
387 b2cfc4e2 2003-09-30 devnull but that will change if pointers and integers are different sizes.
391 b2cfc4e2 2003-09-30 devnull verb takes no arguments; it copies the error string returned by a call to
392 d32deab1 2020-08-16 rsc .MR errstr (3) .
394 b2cfc4e2 2003-09-30 devnull Custom verbs may be installed using
395 d32deab1 2020-08-16 rsc .MR fmtinstall (3) .
396 b2cfc4e2 2003-09-30 devnull .SH EXAMPLE
397 b2cfc4e2 2003-09-30 devnull This function prints an error message with a variable
398 b2cfc4e2 2003-09-30 devnull number of arguments and then quits.
401 b2cfc4e2 2003-09-30 devnull .ta 6n +6n +6n
402 b2cfc4e2 2003-09-30 devnull void fatal(char *msg, ...)
404 b2cfc4e2 2003-09-30 devnull char buf[1024], *out;
405 b2cfc4e2 2003-09-30 devnull va_list arg;
407 c8b6342d 2005-01-13 devnull out = seprint(buf, buf+sizeof buf, "Fatal error: ");
408 b2cfc4e2 2003-09-30 devnull va_start(arg, msg);
409 b2cfc4e2 2003-09-30 devnull out = vseprint(out, buf+sizeof buf, msg, arg);
410 b2cfc4e2 2003-09-30 devnull va_end(arg);
411 b2cfc4e2 2003-09-30 devnull write(2, buf, out-buf);
412 c8b6342d 2005-01-13 devnull exits("fatal error");
415 93aa30a8 2005-01-14 devnull .SH SOURCE
416 adc93f60 2005-01-14 devnull .B \*9/src/lib9/fmt
417 b2cfc4e2 2003-09-30 devnull .SH SEE ALSO
418 d32deab1 2020-08-16 rsc .MR fmtinstall (3) ,
419 d32deab1 2020-08-16 rsc .MR fprintf (3) ,
421 b2cfc4e2 2003-09-30 devnull .SH DIAGNOSTICS
422 b2cfc4e2 2003-09-30 devnull Routines that write to a file descriptor or call
423 b2cfc4e2 2003-09-30 devnull .IR malloc
425 b2cfc4e2 2003-09-30 devnull .IR errstr .
426 b2cfc4e2 2003-09-30 devnull .SH BUGS
427 b2cfc4e2 2003-09-30 devnull The formatting is close to that specified for ANSI
428 d32deab1 2020-08-16 rsc .MR fprintf (3) ;
429 b2cfc4e2 2003-09-30 devnull the main difference is that
433 c8b6342d 2005-01-13 devnull are not in ANSI and
435 c8b6342d 2005-01-13 devnull is a flag here instead of a verb.
436 b2cfc4e2 2003-09-30 devnull Also, and distinctly not a bug,
437 b2cfc4e2 2003-09-30 devnull .I print
438 b2cfc4e2 2003-09-30 devnull and friends generate
440 b2cfc4e2 2003-09-30 devnull rather than
441 b2cfc4e2 2003-09-30 devnull .SM ASCII.
443 b2cfc4e2 2003-09-30 devnull There is no
444 c8b6342d 2005-01-13 devnull .IR runeprint ,
445 c8b6342d 2005-01-13 devnull .IR runefprint ,
446 b2cfc4e2 2003-09-30 devnull etc. because runes are byte-order dependent and should not be written directly to a file; use the
447 b2cfc4e2 2003-09-30 devnull UTF output of
448 b2cfc4e2 2003-09-30 devnull .I print
450 b2cfc4e2 2003-09-30 devnull .I fprint
451 b2cfc4e2 2003-09-30 devnull instead.
453 b2cfc4e2 2003-09-30 devnull .I sprint
454 b2cfc4e2 2003-09-30 devnull is deprecated for safety reasons; use
455 b2cfc4e2 2003-09-30 devnull .IR snprint ,
456 b2cfc4e2 2003-09-30 devnull .IR seprint ,
458 b2cfc4e2 2003-09-30 devnull .I smprint
459 b2cfc4e2 2003-09-30 devnull instead.
460 b2cfc4e2 2003-09-30 devnull Safety also precludes the existence of
461 b2cfc4e2 2003-09-30 devnull .IR runesprint .
