1 78e51a8c 2005-01-14 devnull .\" diffs from /usr/local/plan9/man/man3/print.3:
3 78e51a8c 2005-01-14 devnull .\" - include different headers
4 78e51a8c 2005-01-14 devnull .\" - drop reference to bio(3)
5 78e51a8c 2005-01-14 devnull .\" - change exits to exit
6 78e51a8c 2005-01-14 devnull .\" - text about unsigned verbs
7 78e51a8c 2005-01-14 devnull .\" - source pointer
9 78e51a8c 2005-01-14 devnull .TH PRINT 3
11 78e51a8c 2005-01-14 devnull print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output
12 78e51a8c 2005-01-14 devnull .SH SYNOPSIS
13 78e51a8c 2005-01-14 devnull .B #include <utf.h>
15 78e51a8c 2005-01-14 devnull .B #include <fmt.h>
17 78e51a8c 2005-01-14 devnull .ta \w'\fLchar* 'u
19 78e51a8c 2005-01-14 devnull int print(char *format, ...)
22 78e51a8c 2005-01-14 devnull int fprint(int fd, char *format, ...)
25 78e51a8c 2005-01-14 devnull int sprint(char *s, char *format, ...)
28 78e51a8c 2005-01-14 devnull int snprint(char *s, int len, char *format, ...)
31 78e51a8c 2005-01-14 devnull char* seprint(char *s, char *e, char *format, ...)
34 78e51a8c 2005-01-14 devnull char* smprint(char *format, ...)
37 78e51a8c 2005-01-14 devnull int runesprint(Rune *s, char *format, ...)
40 78e51a8c 2005-01-14 devnull int runesnprint(Rune *s, int len, char *format, ...)
43 78e51a8c 2005-01-14 devnull Rune* runeseprint(Rune *s, Rune *e, char *format, ...)
46 78e51a8c 2005-01-14 devnull Rune* runesmprint(char *format, ...)
49 78e51a8c 2005-01-14 devnull int vfprint(int fd, char *format, va_list v)
52 78e51a8c 2005-01-14 devnull int vsnprint(char *s, int len, char *format, va_list v)
55 78e51a8c 2005-01-14 devnull char* vseprint(char *s, char *e, char *format, va_list v)
58 78e51a8c 2005-01-14 devnull char* vsmprint(char *format, va_list v)
61 78e51a8c 2005-01-14 devnull int runevsnprint(Rune *s, int len, char *format, va_list v)
64 78e51a8c 2005-01-14 devnull Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v)
67 78e51a8c 2005-01-14 devnull Rune* runevsmprint(Rune *format, va_list v)
70 78e51a8c 2005-01-14 devnull .SH DESCRIPTION
72 78e51a8c 2005-01-14 devnull writes text to the standard output.
73 78e51a8c 2005-01-14 devnull .I Fprint
74 78e51a8c 2005-01-14 devnull writes to the named output
75 78e51a8c 2005-01-14 devnull file descriptor:
76 78e51a8c 2005-01-14 devnull a buffered form
77 78e51a8c 2005-01-14 devnull is described in
78 78e51a8c 2005-01-14 devnull .IR bio (3).
79 78e51a8c 2005-01-14 devnull .I Sprint
80 78e51a8c 2005-01-14 devnull places text
81 78e51a8c 2005-01-14 devnull followed by the NUL character
82 78e51a8c 2005-01-14 devnull .RB ( \e0 )
83 78e51a8c 2005-01-14 devnull in consecutive bytes starting at
85 78e51a8c 2005-01-14 devnull it is the user's responsibility to ensure that
86 78e51a8c 2005-01-14 devnull enough storage is available.
87 78e51a8c 2005-01-14 devnull Each function returns the number of bytes
88 78e51a8c 2005-01-14 devnull transmitted (not including the NUL
89 78e51a8c 2005-01-14 devnull in the case of
90 78e51a8c 2005-01-14 devnull .IR sprint ),
92 78e51a8c 2005-01-14 devnull a negative value if an output error was encountered.
94 78e51a8c 2005-01-14 devnull .I Snprint
96 78e51a8c 2005-01-14 devnull .IR sprint ,
97 78e51a8c 2005-01-14 devnull but will not place more than
101 78e51a8c 2005-01-14 devnull Its result is always NUL-terminated and holds the maximal
102 78e51a8c 2005-01-14 devnull number of complete UTF-8 characters that can fit.
103 78e51a8c 2005-01-14 devnull .I Seprint
105 78e51a8c 2005-01-14 devnull .IR snprint ,
106 78e51a8c 2005-01-14 devnull except that the end is indicated by a pointer
108 78e51a8c 2005-01-14 devnull rather than a count and the return value points to the terminating NUL of the
109 78e51a8c 2005-01-14 devnull resulting string.
110 78e51a8c 2005-01-14 devnull .I Smprint
112 78e51a8c 2005-01-14 devnull .IR sprint ,
113 78e51a8c 2005-01-14 devnull except that it prints into and returns a string of the required length, which is
114 78e51a8c 2005-01-14 devnull allocated by
115 78e51a8c 2005-01-14 devnull .IR malloc (3).
117 78e51a8c 2005-01-14 devnull The routines
118 78e51a8c 2005-01-14 devnull .IR runesprint ,
119 78e51a8c 2005-01-14 devnull .IR runesnprint ,
120 78e51a8c 2005-01-14 devnull .IR runeseprint ,
122 78e51a8c 2005-01-14 devnull .I runesmprint
123 78e51a8c 2005-01-14 devnull are the same as
124 78e51a8c 2005-01-14 devnull .IR sprint ,
125 78e51a8c 2005-01-14 devnull .IR snprint ,
126 78e51a8c 2005-01-14 devnull .IR seprint
128 78e51a8c 2005-01-14 devnull .I smprint
129 78e51a8c 2005-01-14 devnull except that their output is rune strings instead of byte strings.
131 78e51a8c 2005-01-14 devnull Finally, the routines
132 78e51a8c 2005-01-14 devnull .IR vfprint ,
133 78e51a8c 2005-01-14 devnull .IR vsnprint ,
134 78e51a8c 2005-01-14 devnull .IR vseprint ,
135 78e51a8c 2005-01-14 devnull .IR vsmprint ,
136 78e51a8c 2005-01-14 devnull .IR runevsnprint ,
137 78e51a8c 2005-01-14 devnull .IR runevseprint ,
139 78e51a8c 2005-01-14 devnull .I runevsmprint
140 78e51a8c 2005-01-14 devnull are like their
141 78e51a8c 2005-01-14 devnull .BR v-less
142 78e51a8c 2005-01-14 devnull relatives except they take as arguments a
143 78e51a8c 2005-01-14 devnull .B va_list
144 78e51a8c 2005-01-14 devnull parameter, so they can be called within a variadic function.
145 78e51a8c 2005-01-14 devnull The Example section shows a representative usage.
147 78e51a8c 2005-01-14 devnull Each of these functions
148 78e51a8c 2005-01-14 devnull converts, formats, and prints its
149 78e51a8c 2005-01-14 devnull trailing arguments
150 78e51a8c 2005-01-14 devnull under control of a
151 78e51a8c 2005-01-14 devnull .IR format
155 78e51a8c 2005-01-14 devnull contains two types of objects:
156 78e51a8c 2005-01-14 devnull plain characters, which are simply copied to the
157 78e51a8c 2005-01-14 devnull output stream,
158 78e51a8c 2005-01-14 devnull and conversion specifications,
159 78e51a8c 2005-01-14 devnull each of which results in fetching of
160 78e51a8c 2005-01-14 devnull zero or more
161 78e51a8c 2005-01-14 devnull arguments.
162 78e51a8c 2005-01-14 devnull The results are undefined if there are arguments of the
163 78e51a8c 2005-01-14 devnull wrong type or too few
164 78e51a8c 2005-01-14 devnull arguments for the format.
165 78e51a8c 2005-01-14 devnull If the format is exhausted while
166 78e51a8c 2005-01-14 devnull arguments remain, the excess
167 78e51a8c 2005-01-14 devnull is ignored.
169 78e51a8c 2005-01-14 devnull Each conversion specification has the following format:
171 78e51a8c 2005-01-14 devnull .B "% [flags] verb
173 78e51a8c 2005-01-14 devnull The verb is a single character and each flag is a single character or a
174 78e51a8c 2005-01-14 devnull (decimal) numeric string.
175 78e51a8c 2005-01-14 devnull Up to two numeric strings may be used;
176 78e51a8c 2005-01-14 devnull the first is called
177 78e51a8c 2005-01-14 devnull .IR width ,
178 78e51a8c 2005-01-14 devnull the second
179 78e51a8c 2005-01-14 devnull .IR precision .
180 78e51a8c 2005-01-14 devnull A period can be used to separate them, and if the period is
181 78e51a8c 2005-01-14 devnull present then
182 78e51a8c 2005-01-14 devnull .I width
184 78e51a8c 2005-01-14 devnull .I precision
185 78e51a8c 2005-01-14 devnull are taken to be zero if missing, otherwise they are `omitted'.
186 78e51a8c 2005-01-14 devnull Either or both of the numbers may be replaced with the character
188 78e51a8c 2005-01-14 devnull meaning that the actual number will be obtained from the argument list
189 78e51a8c 2005-01-14 devnull as an integer.
190 78e51a8c 2005-01-14 devnull The flags and numbers are arguments to
193 78e51a8c 2005-01-14 devnull described below.
195 78e51a8c 2005-01-14 devnull The numeric verbs
204 78e51a8c 2005-01-14 devnull format their arguments in decimal, decimal,
205 78e51a8c 2005-01-14 devnull unsigned decimal, octal, binary, hexadecimal, and upper case hexadecimal.
206 78e51a8c 2005-01-14 devnull Each interprets the flags
209 78e51a8c 2005-01-14 devnull .BR hh ,
216 78e51a8c 2005-01-14 devnull to mean pad with zeros,
217 78e51a8c 2005-01-14 devnull short, byte, long, always print a sign, left justified, commas every three digits,
218 78e51a8c 2005-01-14 devnull and alternate format.
219 78e51a8c 2005-01-14 devnull Also, a space character in the flag
220 78e51a8c 2005-01-14 devnull position is like
222 78e51a8c 2005-01-14 devnull but prints a space instead of a plus sign for non-negative values.
223 78e51a8c 2005-01-14 devnull If neither
224 78e51a8c 2005-01-14 devnull short nor long is specified,
225 78e51a8c 2005-01-14 devnull then the argument is an
226 78e51a8c 2005-01-14 devnull .BR int .
227 78e51a8c 2005-01-14 devnull If an unsigned verb is specified,
228 78e51a8c 2005-01-14 devnull then the argument is interpreted as a
229 78e51a8c 2005-01-14 devnull positive number and no sign is output;
230 78e51a8c 2005-01-14 devnull space and
232 78e51a8c 2005-01-14 devnull flags are ignored for unsigned verbs.
235 78e51a8c 2005-01-14 devnull flags are given,
236 78e51a8c 2005-01-14 devnull then the argument is interpreted as a
237 78e51a8c 2005-01-14 devnull .B vlong
238 78e51a8c 2005-01-14 devnull (usually an 8-byte, sometimes a 4-byte integer).
240 78e51a8c 2005-01-14 devnull .I precision
241 78e51a8c 2005-01-14 devnull is not omitted, the number is padded on the left with zeros
242 78e51a8c 2005-01-14 devnull until at least
243 78e51a8c 2005-01-14 devnull .I precision
244 78e51a8c 2005-01-14 devnull digits appear.
246 78e51a8c 2005-01-14 devnull .I precision
247 78e51a8c 2005-01-14 devnull is explicitly 0, and the number is 0,
248 78e51a8c 2005-01-14 devnull no digits are generated, and alternate formatting
249 78e51a8c 2005-01-14 devnull does not apply.
250 78e51a8c 2005-01-14 devnull Then, if alternate format is specified,
253 78e51a8c 2005-01-14 devnull conversion, the number is preceded by a
255 78e51a8c 2005-01-14 devnull if it doesn't already begin with one.
256 78e51a8c 2005-01-14 devnull For non-zero numbers and
258 78e51a8c 2005-01-14 devnull conversion, the number is preceded by
259 78e51a8c 2005-01-14 devnull .BR 0x ;
262 78e51a8c 2005-01-14 devnull conversion, the number is preceded by
263 78e51a8c 2005-01-14 devnull .BR 0X .
264 78e51a8c 2005-01-14 devnull Finally, if
265 78e51a8c 2005-01-14 devnull .I width
266 78e51a8c 2005-01-14 devnull is not omitted, the number is padded on the left (or right, if
267 78e51a8c 2005-01-14 devnull left justification is specified) with enough blanks to
268 78e51a8c 2005-01-14 devnull make the field at least
269 78e51a8c 2005-01-14 devnull .I width
270 78e51a8c 2005-01-14 devnull characters long.
272 78e51a8c 2005-01-14 devnull The floating point verbs
280 78e51a8c 2005-01-14 devnull .B double
281 78e51a8c 2005-01-14 devnull argument.
282 78e51a8c 2005-01-14 devnull Each interprets the flags
289 78e51a8c 2005-01-14 devnull to mean pad with zeros,
290 78e51a8c 2005-01-14 devnull long double argument,
291 78e51a8c 2005-01-14 devnull always print a sign,
292 78e51a8c 2005-01-14 devnull left justified,
294 78e51a8c 2005-01-14 devnull alternate format.
295 78e51a8c 2005-01-14 devnull .I Width
296 78e51a8c 2005-01-14 devnull is the minimum field width and,
297 78e51a8c 2005-01-14 devnull if the converted value takes up less than
298 78e51a8c 2005-01-14 devnull .I width
299 78e51a8c 2005-01-14 devnull characters, it is padded on the left (or right, if `left justified')
300 78e51a8c 2005-01-14 devnull with spaces.
301 78e51a8c 2005-01-14 devnull .I Precision
302 78e51a8c 2005-01-14 devnull is the number of digits that are converted after the decimal place for
307 78e51a8c 2005-01-14 devnull conversions,
309 78e51a8c 2005-01-14 devnull .I precision
310 78e51a8c 2005-01-14 devnull is the maximum number of significant digits for
314 78e51a8c 2005-01-14 devnull conversions.
317 78e51a8c 2005-01-14 devnull verb produces output of the form
318 78e51a8c 2005-01-14 devnull .RB [ - ] digits [ .digits\fR].
320 78e51a8c 2005-01-14 devnull conversion appends an exponent
321 78e51a8c 2005-01-14 devnull .BR E [ - ] digits ,
324 78e51a8c 2005-01-14 devnull conversion appends an exponent
325 78e51a8c 2005-01-14 devnull .BR e [ - ] digits .
328 78e51a8c 2005-01-14 devnull verb will output the argument in either
332 78e51a8c 2005-01-14 devnull with the goal of producing the smallest output.
333 78e51a8c 2005-01-14 devnull Also, trailing zeros are omitted from the fraction part of
334 78e51a8c 2005-01-14 devnull the output, and a trailing decimal point appears only if it is followed
335 78e51a8c 2005-01-14 devnull by a digit.
338 78e51a8c 2005-01-14 devnull verb is similar, but uses
340 78e51a8c 2005-01-14 devnull format instead of
342 78e51a8c 2005-01-14 devnull When alternate format is specified, the result will always contain a decimal point,
347 78e51a8c 2005-01-14 devnull conversions, trailing zeros are not removed.
351 78e51a8c 2005-01-14 devnull verb copies a string
352 78e51a8c 2005-01-14 devnull (pointer to
353 78e51a8c 2005-01-14 devnull .BR char )
354 78e51a8c 2005-01-14 devnull to the output.
355 78e51a8c 2005-01-14 devnull The number of characters copied
356 78e51a8c 2005-01-14 devnull .RI ( n )
357 78e51a8c 2005-01-14 devnull is the minimum
358 78e51a8c 2005-01-14 devnull of the size of the string and
359 78e51a8c 2005-01-14 devnull .IR precision .
362 78e51a8c 2005-01-14 devnull characters are justified within a field of
363 78e51a8c 2005-01-14 devnull .I width
364 78e51a8c 2005-01-14 devnull characters as described above.
366 78e51a8c 2005-01-14 devnull .I precision
367 78e51a8c 2005-01-14 devnull is given, it is safe for the string not to be nul-terminated
368 78e51a8c 2005-01-14 devnull as long as it is at least
369 78e51a8c 2005-01-14 devnull .I precision
370 78e51a8c 2005-01-14 devnull characters (not bytes!) long.
373 78e51a8c 2005-01-14 devnull verb is similar, but it interprets its pointer as an array
374 78e51a8c 2005-01-14 devnull of runes (see
375 78e51a8c 2005-01-14 devnull .IR utf (7));
376 78e51a8c 2005-01-14 devnull the runes are converted to
378 78e51a8c 2005-01-14 devnull before output.
382 78e51a8c 2005-01-14 devnull verb copies a single
384 78e51a8c 2005-01-14 devnull (promoted to
385 78e51a8c 2005-01-14 devnull .BR int )
386 78e51a8c 2005-01-14 devnull justified within a field of
387 78e51a8c 2005-01-14 devnull .I width
388 78e51a8c 2005-01-14 devnull characters as described above.
391 78e51a8c 2005-01-14 devnull verb is similar, but works on runes.
395 78e51a8c 2005-01-14 devnull verb formats a pointer value.
396 78e51a8c 2005-01-14 devnull At the moment, it is a synonym for
398 78e51a8c 2005-01-14 devnull but that will change if pointers and integers are different sizes.
402 78e51a8c 2005-01-14 devnull verb takes no arguments; it copies the error string returned by a call to
403 78e51a8c 2005-01-14 devnull .IR strerror (3)
404 78e51a8c 2005-01-14 devnull with an argument of
405 78e51a8c 2005-01-14 devnull .IR errno.
407 78e51a8c 2005-01-14 devnull Custom verbs may be installed using
408 78e51a8c 2005-01-14 devnull .IR fmtinstall (3).
409 78e51a8c 2005-01-14 devnull .SH EXAMPLE
410 78e51a8c 2005-01-14 devnull This function prints an error message with a variable
411 78e51a8c 2005-01-14 devnull number of arguments and then quits.
414 78e51a8c 2005-01-14 devnull .ta 6n +6n +6n
415 78e51a8c 2005-01-14 devnull void fatal(char *msg, ...)
417 78e51a8c 2005-01-14 devnull char buf[1024], *out;
418 78e51a8c 2005-01-14 devnull va_list arg;
420 78e51a8c 2005-01-14 devnull out = seprint(buf, buf+sizeof buf, "Fatal error: ");
421 78e51a8c 2005-01-14 devnull va_start(arg, msg);
422 78e51a8c 2005-01-14 devnull out = vseprint(out, buf+sizeof buf, msg, arg);
423 78e51a8c 2005-01-14 devnull va_end(arg);
424 78e51a8c 2005-01-14 devnull write(2, buf, out-buf);
425 78e51a8c 2005-01-14 devnull exit(1);
428 78e51a8c 2005-01-14 devnull .SH SOURCE
429 a3993885 2017-09-01 rsc .B https://9fans.github.io/plan9port/unix
430 78e51a8c 2005-01-14 devnull .SH SEE ALSO
431 78e51a8c 2005-01-14 devnull .IR fmtinstall (3),
432 78e51a8c 2005-01-14 devnull .IR fprintf (3),
433 78e51a8c 2005-01-14 devnull .IR utf (7)
434 78e51a8c 2005-01-14 devnull .SH DIAGNOSTICS
435 78e51a8c 2005-01-14 devnull Routines that write to a file descriptor or call
436 78e51a8c 2005-01-14 devnull .IR malloc
438 78e51a8c 2005-01-14 devnull .IR errstr .
439 78e51a8c 2005-01-14 devnull .SH BUGS
440 78e51a8c 2005-01-14 devnull The formatting is close to that specified for ANSI
441 78e51a8c 2005-01-14 devnull .IR fprintf (3);
442 78e51a8c 2005-01-14 devnull the main difference is that
446 78e51a8c 2005-01-14 devnull are not in ANSI and some
448 78e51a8c 2005-01-14 devnull verbs and syntax are missing.
449 78e51a8c 2005-01-14 devnull Also, and distinctly not a bug,
450 78e51a8c 2005-01-14 devnull .I print
451 78e51a8c 2005-01-14 devnull and friends generate
453 78e51a8c 2005-01-14 devnull rather than
454 78e51a8c 2005-01-14 devnull .SM ASCII.
456 78e51a8c 2005-01-14 devnull There is no
457 78e51a8c 2005-01-14 devnull .IR runeprint ,
458 78e51a8c 2005-01-14 devnull .IR runefprint ,
459 78e51a8c 2005-01-14 devnull etc. because runes are byte-order dependent and should not be written directly to a file; use the
460 78e51a8c 2005-01-14 devnull UTF output of
461 78e51a8c 2005-01-14 devnull .I print
463 78e51a8c 2005-01-14 devnull .I fprint
464 78e51a8c 2005-01-14 devnull instead.
466 78e51a8c 2005-01-14 devnull .I sprint
467 78e51a8c 2005-01-14 devnull is deprecated for safety reasons; use
468 78e51a8c 2005-01-14 devnull .IR snprint ,
469 78e51a8c 2005-01-14 devnull .IR seprint ,
471 78e51a8c 2005-01-14 devnull .I smprint
472 78e51a8c 2005-01-14 devnull instead.
473 78e51a8c 2005-01-14 devnull Safety also precludes the existence of
474 78e51a8c 2005-01-14 devnull .IR runesprint .
