1 b2cfc4e2 2003-09-30 devnull .TH PRINT 3
11 b2cfc4e2 2003-09-30 devnull print, fprint, sprint, snprint, seprint, smprint, vfprint, vsnprint, vseprint, vsmprint \- print formatted output
12 b2cfc4e2 2003-09-30 devnull .SH SYNOPSIS
13 b2cfc4e2 2003-09-30 devnull .B #include <utf.h>
15 b2cfc4e2 2003-09-30 devnull .B #include <fmt.h>
17 b2cfc4e2 2003-09-30 devnull .ta \w'\fLchar* 'u
19 b2cfc4e2 2003-09-30 devnull int print(char *format, ...)
22 b2cfc4e2 2003-09-30 devnull int fprint(int fd, char *format, ...)
25 b2cfc4e2 2003-09-30 devnull int sprint(char *s, char *format, ...)
28 b2cfc4e2 2003-09-30 devnull int snprint(char *s, int len, char *format, ...)
31 b2cfc4e2 2003-09-30 devnull char* seprint(char *s, char *e, char *format, ...)
34 b2cfc4e2 2003-09-30 devnull char* smprint(char *format, ...)
37 b2cfc4e2 2003-09-30 devnull int runesprint(Rune *s, char *format, ...)
40 b2cfc4e2 2003-09-30 devnull int runesnprint(Rune *s, int len, char *format, ...)
43 b2cfc4e2 2003-09-30 devnull Rune* runeseprint(Rune *s, Rune *e, char *format, ...)
46 b2cfc4e2 2003-09-30 devnull Rune* runesmprint(char *format, ...)
49 b2cfc4e2 2003-09-30 devnull int vfprint(int fd, char *format, va_list v)
52 b2cfc4e2 2003-09-30 devnull int vsnprint(char *s, int len, char *format, va_list v)
55 b2cfc4e2 2003-09-30 devnull char* vseprint(char *s, char *e, char *format, va_list v)
58 b2cfc4e2 2003-09-30 devnull char* vsmprint(char *format, va_list v)
61 b2cfc4e2 2003-09-30 devnull int runevsnprint(Rune *s, int len, char *format, va_list v)
64 b2cfc4e2 2003-09-30 devnull Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v)
67 b2cfc4e2 2003-09-30 devnull Rune* runevsmprint(Rune *format, va_list v)
70 b2cfc4e2 2003-09-30 devnull .SH DESCRIPTION
72 b2cfc4e2 2003-09-30 devnull writes text to the standard output.
73 b2cfc4e2 2003-09-30 devnull .I Fprint
74 b2cfc4e2 2003-09-30 devnull writes to the named output
75 b2cfc4e2 2003-09-30 devnull file descriptor.
76 b2cfc4e2 2003-09-30 devnull .I Sprint
77 b2cfc4e2 2003-09-30 devnull places text
78 b2cfc4e2 2003-09-30 devnull followed by the NUL character
79 b2cfc4e2 2003-09-30 devnull .RB ( \e0 )
80 b2cfc4e2 2003-09-30 devnull in consecutive bytes starting at
82 b2cfc4e2 2003-09-30 devnull it is the user's responsibility to ensure that
83 b2cfc4e2 2003-09-30 devnull enough storage is available.
84 b2cfc4e2 2003-09-30 devnull Each function returns the number of bytes
85 b2cfc4e2 2003-09-30 devnull transmitted (not including the NUL
86 b2cfc4e2 2003-09-30 devnull in the case of
87 b2cfc4e2 2003-09-30 devnull .IR sprint ),
89 b2cfc4e2 2003-09-30 devnull a negative value if an output error was encountered.
91 b2cfc4e2 2003-09-30 devnull .I Snprint
93 b2cfc4e2 2003-09-30 devnull .IR sprint ,
94 b2cfc4e2 2003-09-30 devnull but will not place more than
98 b2cfc4e2 2003-09-30 devnull Its result is always NUL-terminated and holds the maximal
99 b2cfc4e2 2003-09-30 devnull number of characters that can fit.
100 b2cfc4e2 2003-09-30 devnull .I Seprint
102 b2cfc4e2 2003-09-30 devnull .IR snprint ,
103 b2cfc4e2 2003-09-30 devnull except that the end is indicated by a pointer
105 b2cfc4e2 2003-09-30 devnull rather than a count and the return value points to the terminating NUL of the
106 b2cfc4e2 2003-09-30 devnull resulting string.
107 b2cfc4e2 2003-09-30 devnull .I Smprint
109 b2cfc4e2 2003-09-30 devnull .IR sprint ,
110 b2cfc4e2 2003-09-30 devnull except that it prints into and returns a string of the required length, which is
111 b2cfc4e2 2003-09-30 devnull allocated by
112 b2cfc4e2 2003-09-30 devnull .IR malloc (3).
114 b2cfc4e2 2003-09-30 devnull The routines
115 b2cfc4e2 2003-09-30 devnull .IR runesprint ,
116 b2cfc4e2 2003-09-30 devnull .IR runesnprint ,
117 b2cfc4e2 2003-09-30 devnull .IR runeseprint ,
119 b2cfc4e2 2003-09-30 devnull .I runesmprint
120 b2cfc4e2 2003-09-30 devnull are the same as
121 b2cfc4e2 2003-09-30 devnull .IR sprint ,
122 b2cfc4e2 2003-09-30 devnull .IR snprint ,
123 b2cfc4e2 2003-09-30 devnull .IR seprint
125 b2cfc4e2 2003-09-30 devnull .I smprint
126 b2cfc4e2 2003-09-30 devnull except that their output is rune strings instead of byte strings.
128 b2cfc4e2 2003-09-30 devnull Finally, the routines
129 b2cfc4e2 2003-09-30 devnull .IR vfprint ,
130 b2cfc4e2 2003-09-30 devnull .IR vsnprint ,
131 b2cfc4e2 2003-09-30 devnull .IR vseprint ,
132 b2cfc4e2 2003-09-30 devnull .IR vsmprint ,
133 b2cfc4e2 2003-09-30 devnull .IR runevsnprint ,
134 b2cfc4e2 2003-09-30 devnull .IR runevseprint ,
136 b2cfc4e2 2003-09-30 devnull .I runevsmprint
137 b2cfc4e2 2003-09-30 devnull are like their
138 b2cfc4e2 2003-09-30 devnull .BR v-less
139 b2cfc4e2 2003-09-30 devnull relatives except they take as arguments a
140 b2cfc4e2 2003-09-30 devnull .B va_list
141 b2cfc4e2 2003-09-30 devnull parameter, so they can be called within a variadic function.
142 b2cfc4e2 2003-09-30 devnull The Example section shows a representative usage.
144 b2cfc4e2 2003-09-30 devnull Each of these functions
145 b2cfc4e2 2003-09-30 devnull converts, formats, and prints its
146 b2cfc4e2 2003-09-30 devnull trailing arguments
147 b2cfc4e2 2003-09-30 devnull under control of a
148 b2cfc4e2 2003-09-30 devnull .IR format
152 b2cfc4e2 2003-09-30 devnull contains two types of objects:
153 b2cfc4e2 2003-09-30 devnull plain characters, which are simply copied to the
154 b2cfc4e2 2003-09-30 devnull output stream,
155 b2cfc4e2 2003-09-30 devnull and conversion specifications,
156 b2cfc4e2 2003-09-30 devnull each of which results in fetching of
157 b2cfc4e2 2003-09-30 devnull zero or more
158 b2cfc4e2 2003-09-30 devnull arguments.
159 b2cfc4e2 2003-09-30 devnull The results are undefined if there are arguments of the
160 b2cfc4e2 2003-09-30 devnull wrong type or too few
161 b2cfc4e2 2003-09-30 devnull arguments for the format.
162 b2cfc4e2 2003-09-30 devnull If the format is exhausted while
163 b2cfc4e2 2003-09-30 devnull arguments remain, the excess
164 b2cfc4e2 2003-09-30 devnull is ignored.
166 b2cfc4e2 2003-09-30 devnull Each conversion specification has the following format:
168 b2cfc4e2 2003-09-30 devnull .B "% [flags] verb
170 b2cfc4e2 2003-09-30 devnull The verb is a single character and each flag is a single character or a
171 b2cfc4e2 2003-09-30 devnull (decimal) numeric string.
172 b2cfc4e2 2003-09-30 devnull Up to two numeric strings may be used;
173 b2cfc4e2 2003-09-30 devnull the first is called
174 b2cfc4e2 2003-09-30 devnull .IR width ,
175 b2cfc4e2 2003-09-30 devnull the second
176 b2cfc4e2 2003-09-30 devnull .IR precision .
177 b2cfc4e2 2003-09-30 devnull A period can be used to separate them, and if the period is
178 b2cfc4e2 2003-09-30 devnull present then
179 b2cfc4e2 2003-09-30 devnull .I width
181 b2cfc4e2 2003-09-30 devnull .I precision
182 b2cfc4e2 2003-09-30 devnull are taken to be zero if missing, otherwise they are `omitted'.
183 b2cfc4e2 2003-09-30 devnull Either or both of the numbers may be replaced with the character
185 b2cfc4e2 2003-09-30 devnull meaning that the actual number will be obtained from the argument list
186 b2cfc4e2 2003-09-30 devnull as an integer.
187 b2cfc4e2 2003-09-30 devnull The flags and numbers are arguments to
190 b2cfc4e2 2003-09-30 devnull described below.
192 b2cfc4e2 2003-09-30 devnull The numeric verbs
201 b2cfc4e2 2003-09-30 devnull format their arguments in decimal, decimal,
202 b2cfc4e2 2003-09-30 devnull unsigned decimal, octal, binary, hexadecimal, and upper case hexadecimal.
203 b2cfc4e2 2003-09-30 devnull Each interprets the flags
206 b2cfc4e2 2003-09-30 devnull .BR hh ,
213 b2cfc4e2 2003-09-30 devnull to mean pad with zeros,
214 b2cfc4e2 2003-09-30 devnull short, byte, long, always print a sign, left justified, commas every three digits,
215 b2cfc4e2 2003-09-30 devnull and alternate format.
216 b2cfc4e2 2003-09-30 devnull Also, a space character in the flag
217 b2cfc4e2 2003-09-30 devnull position is like
219 b2cfc4e2 2003-09-30 devnull but prints a space instead of a plus sign for non-negative values.
220 b2cfc4e2 2003-09-30 devnull If neither
221 b2cfc4e2 2003-09-30 devnull short nor long is specified,
222 b2cfc4e2 2003-09-30 devnull then the argument is an
223 b2cfc4e2 2003-09-30 devnull .BR int .
224 b2cfc4e2 2003-09-30 devnull If an unsigned verb is specified,
225 b2cfc4e2 2003-09-30 devnull then the argument is interpreted as a
226 b2cfc4e2 2003-09-30 devnull positive number and no sign is output;
227 b2cfc4e2 2003-09-30 devnull space and
229 b2cfc4e2 2003-09-30 devnull flags are ignored for unsigned verbs.
232 b2cfc4e2 2003-09-30 devnull flags are given,
233 b2cfc4e2 2003-09-30 devnull then the argument is interpreted as a
234 b2cfc4e2 2003-09-30 devnull .B vlong
235 b2cfc4e2 2003-09-30 devnull (usually an 8-byte, sometimes a 4-byte integer).
237 b2cfc4e2 2003-09-30 devnull .I precision
238 b2cfc4e2 2003-09-30 devnull is not omitted, the number is padded on the left with zeros
239 b2cfc4e2 2003-09-30 devnull until at least
240 b2cfc4e2 2003-09-30 devnull .I precision
241 b2cfc4e2 2003-09-30 devnull digits appear.
243 b2cfc4e2 2003-09-30 devnull .I precision
244 b2cfc4e2 2003-09-30 devnull is explicitly 0, and the number is 0,
245 b2cfc4e2 2003-09-30 devnull no digits are generated, and alternate formatting
246 b2cfc4e2 2003-09-30 devnull does not apply.
247 b2cfc4e2 2003-09-30 devnull Then, if alternate format is specified,
250 b2cfc4e2 2003-09-30 devnull conversion, the number is preceded by a
252 b2cfc4e2 2003-09-30 devnull if it doesn't already begin with one.
253 b2cfc4e2 2003-09-30 devnull For non-zero numbers and
255 b2cfc4e2 2003-09-30 devnull conversion, the number is preceded by
256 b2cfc4e2 2003-09-30 devnull .BR 0x ;
259 b2cfc4e2 2003-09-30 devnull conversion, the number is preceded by
260 b2cfc4e2 2003-09-30 devnull .BR 0X .
261 b2cfc4e2 2003-09-30 devnull Finally, if
262 b2cfc4e2 2003-09-30 devnull .I width
263 b2cfc4e2 2003-09-30 devnull is not omitted, the number is padded on the left (or right, if
264 b2cfc4e2 2003-09-30 devnull left justification is specified) with enough blanks to
265 b2cfc4e2 2003-09-30 devnull make the field at least
266 b2cfc4e2 2003-09-30 devnull .I width
267 b2cfc4e2 2003-09-30 devnull characters long.
269 b2cfc4e2 2003-09-30 devnull The floating point verbs
277 b2cfc4e2 2003-09-30 devnull .B double
278 b2cfc4e2 2003-09-30 devnull argument.
279 b2cfc4e2 2003-09-30 devnull Each interprets the flags
286 b2cfc4e2 2003-09-30 devnull to mean pad with zeros,
287 b2cfc4e2 2003-09-30 devnull long double argument,
288 b2cfc4e2 2003-09-30 devnull always print a sign,
289 b2cfc4e2 2003-09-30 devnull left justified,
291 b2cfc4e2 2003-09-30 devnull alternate format.
292 b2cfc4e2 2003-09-30 devnull .I Width
293 b2cfc4e2 2003-09-30 devnull is the minimum field width and,
294 b2cfc4e2 2003-09-30 devnull if the converted value takes up less than
295 b2cfc4e2 2003-09-30 devnull .I width
296 b2cfc4e2 2003-09-30 devnull characters, it is padded on the left (or right, if `left justified')
297 b2cfc4e2 2003-09-30 devnull with spaces.
298 b2cfc4e2 2003-09-30 devnull .I Precision
299 b2cfc4e2 2003-09-30 devnull is the number of digits that are converted after the decimal place for
304 b2cfc4e2 2003-09-30 devnull conversions,
306 b2cfc4e2 2003-09-30 devnull .I precision
307 b2cfc4e2 2003-09-30 devnull is the maximum number of significant digits for
311 b2cfc4e2 2003-09-30 devnull conversions.
314 b2cfc4e2 2003-09-30 devnull verb produces output of the form
315 b2cfc4e2 2003-09-30 devnull .RB [ - ] digits [ .digits\fR].
317 b2cfc4e2 2003-09-30 devnull conversion appends an exponent
318 b2cfc4e2 2003-09-30 devnull .BR E [ - ] digits ,
321 b2cfc4e2 2003-09-30 devnull conversion appends an exponent
322 b2cfc4e2 2003-09-30 devnull .BR e [ - ] digits .
325 b2cfc4e2 2003-09-30 devnull verb will output the argument in either
329 b2cfc4e2 2003-09-30 devnull with the goal of producing the smallest output.
330 b2cfc4e2 2003-09-30 devnull Also, trailing zeros are omitted from the fraction part of
331 b2cfc4e2 2003-09-30 devnull the output, and a trailing decimal point appears only if it is followed
332 b2cfc4e2 2003-09-30 devnull by a digit.
335 b2cfc4e2 2003-09-30 devnull verb is similar, but uses
337 b2cfc4e2 2003-09-30 devnull format instead of
339 b2cfc4e2 2003-09-30 devnull When alternate format is specified, the result will always contain a decimal point,
344 b2cfc4e2 2003-09-30 devnull conversions, trailing zeros are not removed.
348 b2cfc4e2 2003-09-30 devnull verb copies a string
349 b2cfc4e2 2003-09-30 devnull (pointer to
350 b2cfc4e2 2003-09-30 devnull .BR char )
351 b2cfc4e2 2003-09-30 devnull to the output.
352 b2cfc4e2 2003-09-30 devnull The number of characters copied
353 b2cfc4e2 2003-09-30 devnull .RI ( n )
354 b2cfc4e2 2003-09-30 devnull is the minimum
355 b2cfc4e2 2003-09-30 devnull of the size of the string and
356 b2cfc4e2 2003-09-30 devnull .IR precision .
359 b2cfc4e2 2003-09-30 devnull characters are justified within a field of
360 b2cfc4e2 2003-09-30 devnull .I width
361 b2cfc4e2 2003-09-30 devnull characters as described above.
363 b2cfc4e2 2003-09-30 devnull .I precision
364 b2cfc4e2 2003-09-30 devnull is given, it is safe for the string not to be nul-terminated
365 b2cfc4e2 2003-09-30 devnull as long as it is at least
366 b2cfc4e2 2003-09-30 devnull .I precision
367 b2cfc4e2 2003-09-30 devnull characters (not bytes!) long.
370 b2cfc4e2 2003-09-30 devnull verb is similar, but it interprets its pointer as an array
371 b2cfc4e2 2003-09-30 devnull of runes (see
372 b2cfc4e2 2003-09-30 devnull .IR utf (7));
373 b2cfc4e2 2003-09-30 devnull the runes are converted to
375 b2cfc4e2 2003-09-30 devnull before output.
379 b2cfc4e2 2003-09-30 devnull verb copies a single
381 b2cfc4e2 2003-09-30 devnull (promoted to
382 b2cfc4e2 2003-09-30 devnull .BR int )
383 b2cfc4e2 2003-09-30 devnull justified within a field of
384 b2cfc4e2 2003-09-30 devnull .I width
385 b2cfc4e2 2003-09-30 devnull characters as described above.
388 b2cfc4e2 2003-09-30 devnull verb is similar, but works on runes.
392 b2cfc4e2 2003-09-30 devnull verb formats a pointer value.
393 b2cfc4e2 2003-09-30 devnull At the moment, it is a synonym for
395 b2cfc4e2 2003-09-30 devnull but that will change if pointers and integers are different sizes.
399 b2cfc4e2 2003-09-30 devnull verb takes no arguments; it copies the error string returned by a call to
400 b2cfc4e2 2003-09-30 devnull .IR strerror (3)
401 b2cfc4e2 2003-09-30 devnull with an argument of
402 b2cfc4e2 2003-09-30 devnull .IR errno.
404 b2cfc4e2 2003-09-30 devnull Custom verbs may be installed using
405 b2cfc4e2 2003-09-30 devnull .IR fmtinstall (3).
406 b2cfc4e2 2003-09-30 devnull .SH EXAMPLE
407 b2cfc4e2 2003-09-30 devnull This function prints an error message with a variable
408 b2cfc4e2 2003-09-30 devnull number of arguments and then quits.
411 b2cfc4e2 2003-09-30 devnull .ta 6n +6n +6n
412 b2cfc4e2 2003-09-30 devnull void fatal(char *msg, ...)
414 b2cfc4e2 2003-09-30 devnull char buf[1024], *out;
415 b2cfc4e2 2003-09-30 devnull va_list arg;
417 b2cfc4e2 2003-09-30 devnull out = vseprint(buf, buf+sizeof buf, "Fatal error: ");
418 b2cfc4e2 2003-09-30 devnull va_start(arg, msg);
419 b2cfc4e2 2003-09-30 devnull out = vseprint(out, buf+sizeof buf, msg, arg);
420 b2cfc4e2 2003-09-30 devnull va_end(arg);
421 b2cfc4e2 2003-09-30 devnull write(2, buf, out-buf);
422 b2cfc4e2 2003-09-30 devnull exit(1);
425 b2cfc4e2 2003-09-30 devnull .SH SEE ALSO
426 b2cfc4e2 2003-09-30 devnull .IR fmtinstall (3),
427 b2cfc4e2 2003-09-30 devnull .IR fprintf (3),
428 b2cfc4e2 2003-09-30 devnull .IR utf (7)
429 b2cfc4e2 2003-09-30 devnull .SH DIAGNOSTICS
430 b2cfc4e2 2003-09-30 devnull Routines that write to a file descriptor or call
431 b2cfc4e2 2003-09-30 devnull .IR malloc
433 b2cfc4e2 2003-09-30 devnull .IR errstr .
434 b2cfc4e2 2003-09-30 devnull .SH BUGS
435 b2cfc4e2 2003-09-30 devnull The formatting is close to that specified for ANSI
436 b2cfc4e2 2003-09-30 devnull .IR fprintf (3);
437 b2cfc4e2 2003-09-30 devnull the main difference is that
441 b2cfc4e2 2003-09-30 devnull are not in ANSI and some
443 b2cfc4e2 2003-09-30 devnull verbs are missing.
444 b2cfc4e2 2003-09-30 devnull Also, and distinctly not a bug,
445 b2cfc4e2 2003-09-30 devnull .I print
446 b2cfc4e2 2003-09-30 devnull and friends generate
448 b2cfc4e2 2003-09-30 devnull rather than
449 b2cfc4e2 2003-09-30 devnull .SM ASCII.
451 b2cfc4e2 2003-09-30 devnull There is no
452 b2cfc4e2 2003-09-30 devnull .BR runeprint ,
453 b2cfc4e2 2003-09-30 devnull .BR runefprint ,
454 b2cfc4e2 2003-09-30 devnull etc. because runes are byte-order dependent and should not be written directly to a file; use the
455 b2cfc4e2 2003-09-30 devnull UTF output of
456 b2cfc4e2 2003-09-30 devnull .I print
458 b2cfc4e2 2003-09-30 devnull .I fprint
459 b2cfc4e2 2003-09-30 devnull instead.
461 b2cfc4e2 2003-09-30 devnull .I sprint
462 b2cfc4e2 2003-09-30 devnull is deprecated for safety reasons; use
463 b2cfc4e2 2003-09-30 devnull .IR snprint ,
464 b2cfc4e2 2003-09-30 devnull .IR seprint ,
466 b2cfc4e2 2003-09-30 devnull .I smprint
467 b2cfc4e2 2003-09-30 devnull instead.
468 b2cfc4e2 2003-09-30 devnull Safety also precludes the existence of
469 b2cfc4e2 2003-09-30 devnull .IR runesprint .
