print.3 (9427B) download
1.deEX
2.ift .ft5
3.nf
4..
5.deEE
6.ft1
7.fi
8..
9.\" diffs from /usr/local/plan9/man/man3/print.3:
10.\"
11.\" - include different headers
12.\" - drop reference to bio(3)
13.\" - change exits to exit
14.\" - text about unsigned verbs
15.\" - source pointer
16.\"
17.TH PRINT 3
18.SH NAME
19print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output
20.SH SYNOPSIS
21.B #include <utf.h>
22.PP
23.B #include <fmt.h>
24.PP
25.ta \w'\fLchar* 'u
26.B
27int print(char *format, ...)
28.PP
29.B
30int fprint(int fd, char *format, ...)
31.PP
32.B
33int sprint(char *s, char *format, ...)
34.PP
35.B
36int snprint(char *s, int len, char *format, ...)
37.PP
38.B
39char* seprint(char *s, char *e, char *format, ...)
40.PP
41.B
42char* smprint(char *format, ...)
43.PP
44.B
45int runesprint(Rune *s, char *format, ...)
46.PP
47.B
48int runesnprint(Rune *s, int len, char *format, ...)
49.PP
50.B
51Rune* runeseprint(Rune *s, Rune *e, char *format, ...)
52.PP
53.B
54Rune* runesmprint(char *format, ...)
55.PP
56.B
57int vfprint(int fd, char *format, va_list v)
58.PP
59.B
60int vsnprint(char *s, int len, char *format, va_list v)
61.PP
62.B
63char* vseprint(char *s, char *e, char *format, va_list v)
64.PP
65.B
66char* vsmprint(char *format, va_list v)
67.PP
68.B
69int runevsnprint(Rune *s, int len, char *format, va_list v)
70.PP
71.B
72Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v)
73.PP
74.B
75Rune* runevsmprint(Rune *format, va_list v)
76.PP
77.B
78.SH DESCRIPTION
79.I Print
80writes text to the standard output.
81.I Fprint
82writes to the named output
83file descriptor:
84a buffered form
85is described in
86.IR bio (3).
87.I Sprint
88places text
89followed by the NUL character
90.RB ( \e0 )
91in consecutive bytes starting at
92.IR s ;
93it is the user's responsibility to ensure that
94enough storage is available.
95Each function returns the number of bytes
96transmitted (not including the NUL
97in the case of
98.IR sprint ),
99or
100a negative value if an output error was encountered.
101.PP
102.I Snprint
103is like
104.IR sprint ,
105but will not place more than
106.I len
107bytes in
108.IR s .
109Its result is always NUL-terminated and holds the maximal
110number of complete UTF-8 characters that can fit.
111.I Seprint
112is like
113.IR snprint ,
114except that the end is indicated by a pointer
115.I e
116rather than a count and the return value points to the terminating NUL of the
117resulting string.
118.I Smprint
119is like
120.IR sprint ,
121except that it prints into and returns a string of the required length, which is
122allocated by
123.IR malloc (3).
124.PP
125The routines
126.IR runesprint ,
127.IR runesnprint ,
128.IR runeseprint ,
129and
130.I runesmprint
131are the same as
132.IR sprint ,
133.IR snprint ,
134.IR seprint
135and
136.I smprint
137except that their output is rune strings instead of byte strings.
138.PP
139Finally, the routines
140.IR vfprint ,
141.IR vsnprint ,
142.IR vseprint ,
143.IR vsmprint ,
144.IR runevsnprint ,
145.IR runevseprint ,
146and
147.I runevsmprint
148are like their
149.BR v-less
150relatives except they take as arguments a
151.B va_list
152parameter, so they can be called within a variadic function.
153The Example section shows a representative usage.
154.PP
155Each of these functions
156converts, formats, and prints its
157trailing arguments
158under control of a
159.IR format
160string.
161The
162format
163contains two types of objects:
164plain characters, which are simply copied to the
165output stream,
166and conversion specifications,
167each of which results in fetching of
168zero or more
169arguments.
170The results are undefined if there are arguments of the
171wrong type or too few
172arguments for the format.
173If the format is exhausted while
174arguments remain, the excess
175is ignored.
176.PP
177Each conversion specification has the following format:
178.IP
179.B "% [flags] verb
180.PP
181The verb is a single character and each flag is a single character or a
182(decimal) numeric string.
183Up to two numeric strings may be used;
184the first is called
185.IR width ,
186the second
187.IR precision .
188A period can be used to separate them, and if the period is
189present then
190.I width
191and
192.I precision
193are taken to be zero if missing, otherwise they are `omitted'.
194Either or both of the numbers may be replaced with the character
195.BR * ,
196meaning that the actual number will be obtained from the argument list
197as an integer.
198The flags and numbers are arguments to
199the
200.I verb
201described below.
202.PP
203The numeric verbs
204.BR d ,
205.BR i ,
206.BR u ,
207.BR o ,
208.BR b ,
209.BR x ,
210and
211.B X
212format their arguments in decimal, decimal,
213unsigned decimal, octal, binary, hexadecimal, and upper case hexadecimal.
214Each interprets the flags
215.BR 0 ,
216.BR h ,
217.BR hh ,
218.BR l ,
219.BR + ,
220.BR - ,
221.BR , ,
222and
223.B #
224to mean pad with zeros,
225short, byte, long, always print a sign, left justified, commas every three digits,
226and alternate format.
227Also, a space character in the flag
228position is like
229.BR + ,
230but prints a space instead of a plus sign for non-negative values.
231If neither
232short nor long is specified,
233then the argument is an
234.BR int .
235If an unsigned verb is specified,
236then the argument is interpreted as a
237positive number and no sign is output;
238space and
239.B +
240flags are ignored for unsigned verbs.
241If two
242.B l
243flags are given,
244then the argument is interpreted as a
245.B vlong
246(usually an 8-byte, sometimes a 4-byte integer).
247If
248.I precision
249is not omitted, the number is padded on the left with zeros
250until at least
251.I precision
252digits appear.
253If
254.I precision
255is explicitly 0, and the number is 0,
256no digits are generated, and alternate formatting
257does not apply.
258Then, if alternate format is specified,
259for
260.B o
261conversion, the number is preceded by a
262.B 0
263if it doesn't already begin with one.
264For non-zero numbers and
265.B x
266conversion, the number is preceded by
267.BR 0x ;
268for
269.B X
270conversion, the number is preceded by
271.BR 0X .
272Finally, if
273.I width
274is not omitted, the number is padded on the left (or right, if
275left justification is specified) with enough blanks to
276make the field at least
277.I width
278characters long.
279.PP
280The floating point verbs
281.BR f ,
282.BR e ,
283.BR E ,
284.BR g ,
285and
286.B G
287take a
288.B double
289argument.
290Each interprets the flags
291.BR 0 ,
292.BR L
293.BR + ,
294.BR - ,
295and
296.B #
297to mean pad with zeros,
298long double argument,
299always print a sign,
300left justified,
301and
302alternate format.
303.I Width
304is the minimum field width and,
305if the converted value takes up less than
306.I width
307characters, it is padded on the left (or right, if `left justified')
308with spaces.
309.I Precision
310is the number of digits that are converted after the decimal place for
311.BR e ,
312.BR E ,
313and
314.B f
315conversions,
316and
317.I precision
318is the maximum number of significant digits for
319.B g
320and
321.B G
322conversions.
323The
324.B f
325verb produces output of the form
326.RB [ - ] digits [ .digits\fR].
327.B E
328conversion appends an exponent
329.BR E [ - ] digits ,
330and
331.B e
332conversion appends an exponent
333.BR e [ - ] digits .
334The
335.B g
336verb will output the argument in either
337.B e
338or
339.B f
340with the goal of producing the smallest output.
341Also, trailing zeros are omitted from the fraction part of
342the output, and a trailing decimal point appears only if it is followed
343by a digit.
344The
345.B G
346verb is similar, but uses
347.B E
348format instead of
349.BR e .
350When alternate format is specified, the result will always contain a decimal point,
351and for
352.B g
353and
354.B G
355conversions, trailing zeros are not removed.
356.PP
357The
358.B s
359verb copies a string
360(pointer to
361.BR char )
362to the output.
363The number of characters copied
364.RI ( n )
365is the minimum
366of the size of the string and
367.IR precision .
368These
369.I n
370characters are justified within a field of
371.I width
372characters as described above.
373If a
374.I precision
375is given, it is safe for the string not to be nul-terminated
376as long as it is at least
377.I precision
378characters (not bytes!) long.
379The
380.B S
381verb is similar, but it interprets its pointer as an array
382of runes (see
383.IR utf (7));
384the runes are converted to
385.SM UTF
386before output.
387.PP
388The
389.B c
390verb copies a single
391.B char
392(promoted to
393.BR int )
394justified within a field of
395.I width
396characters as described above.
397The
398.B C
399verb is similar, but works on runes.
400.PP
401The
402.B p
403verb formats a pointer value.
404At the moment, it is a synonym for
405.BR x ,
406but that will change if pointers and integers are different sizes.
407.PP
408The
409.B r
410verb takes no arguments; it copies the error string returned by a call to
411.IR strerror (3)
412with an argument of
413.IR errno.
414.PP
415Custom verbs may be installed using
416.IR fmtinstall (3).
417.SH EXAMPLE
418This function prints an error message with a variable
419number of arguments and then quits.
420.IP
421.EX
422.ta 6n +6n +6n
423void fatal(char *msg, ...)
424{
425 char buf[1024], *out;
426 va_list arg;
427
428 out = seprint(buf, buf+sizeof buf, "Fatal error: ");
429 va_start(arg, msg);
430 out = vseprint(out, buf+sizeof buf, msg, arg);
431 va_end(arg);
432 write(2, buf, out-buf);
433 exit(1);
434}
435.EE
436.SH SOURCE
437.B https://9fans.github.io/plan9port/unix
438.SH SEE ALSO
439.IR fmtinstall (3),
440.IR fprintf (3),
441.IR utf (7)
442.SH DIAGNOSTICS
443Routines that write to a file descriptor or call
444.IR malloc
445set
446.IR errstr .
447.SH BUGS
448The formatting is close to that specified for ANSI
449.IR fprintf (3);
450the main difference is that
451.B b
452and
453.B r
454are not in ANSI and some
455.B C9X
456verbs and syntax are missing.
457Also, and distinctly not a bug,
458.I print
459and friends generate
460.SM UTF
461rather than
462.SM ASCII.
463.PP
464There is no
465.IR runeprint ,
466.IR runefprint ,
467etc. because runes are byte-order dependent and should not be written directly to a file; use the
468UTF output of
469.I print
470or
471.I fprint
472instead.
473Also,
474.I sprint
475is deprecated for safety reasons; use
476.IR snprint ,
477.IR seprint ,
478or
479.I smprint
480instead.
481Safety also precludes the existence of
482.IR runesprint .