![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to print.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / man / adm / man3|
Return to print.3 CVS log | Up to [Research Unix] / researchv10dc / man / adm / man3 |
1.1 root 1: .TH PRINT 3
2: .CT 2 file_io
3: .SH NAME
4: print, fprint, sprint, fmtinstall \(mi print formatted output
5: .SH SYNOPSIS
6: .nf
7: .BR "int print(format \fR[\fP , arg \fR]\fP ... )"
8: .B char \(**format;
9: .PP
10: .BR "int fprint(fildes, format \fR[\fP , arg \fR]\fP ... )"
11: .B int fildes;
12: .B char \(**format;
13: .PP
14: .BR "int sprint(s, format \fR[\fP , arg \fR]\fP ... )"
15: .B char \(**s, \(**format;
16: .PP
17: .B fmtinstall(c, fn)
18: .B char c;
19: .B int (*fn)();
20: .PP
21: .B strconv(s, f1, f2)
22: .B char *s;
23: .PP
24: .B extern int printcol;
25: .fi
26: .SH DESCRIPTION
27: .I Print
28: places output on the standard output.
29: .I Fprint
30: places output on the named output
31: file descriptor;
32: a buffered form
33: is described in
34: .IR fio (3).
35: .I Sprint
36: places output
37: followed by the null character
38: .RB ( \e0 )
39: in consecutive bytes starting at
40: .IR s ;
41: it is the user's responsibility to ensure that
42: enough storage is available.
43: Each function returns the number of characters
44: transmitted (not including the
45: .B \e0
46: in the case of
47: .IR sprint ),
48: or
49: a negative value if an output error was encountered.
50: .PP
51: Each of these functions
52: converts, formats, and prints its
53: trailing arguments
54: under control of a
55: .IR format
56: string.
57: The
58: .I format
59: contains two types of objects:
60: plain characters, which are simply copied to the
61: output stream,
62: and conversion specifications,
63: each of which results in fetching of
64: zero or more
65: arguments.
66: The results are undefined if there are arguments of the
67: wrong type or too few
68: arguments for the format.
69: If the format is exhausted while
70: arguments remain, the excess
71: are ignored.
72: .PP
73: Each conversion specification has the following format
74: .PP
75: .B "% [flags] [[\(mi] digits [. digits]] verb
76: .PP
77: The
78: .I flags
79: modify the meaning of
80: the conversion verb.
81: The first (possibly negative) number is called
82: .IR f1 ,
83: the second number is
84: .IR f2 .
85: The flags and numbers are arguments to
86: the
87: .I verb
88: described below.
89: .PP
90: The numeric verbs
91: .BR d ,
92: .BR o ,
93: and
94: .B x
95: format their arguments in decimal,
96: octal and hex respectively.
97: Each interprets the flags
98: .BR h ,
99: .BR l ,
100: .BR u ,
101: to mean short,
102: long,
103: and unsigned.
104: If neither
105: short nor long is specified,
106: then the arg is an
107: .BR int .
108: If unsigned is specified,
109: then the arg is interpreted as a
110: positive number and no sign is output.
111: .I F1
112: is the minimum field width and,
113: if negative,
114: means left justified rather than right justified;
115: in both cases, padding is done with blanks.
116: The converted number is padded with
117: .B 0
118: on the left to at least
119: .I f2
120: characters.
121: .PP
122: The floating point verbs
123: .BR f ,
124: .BR e ,
125: and
126: .B g
127: take a double argument.
128: No flags apply to floating point conversions.
129: .I F1
130: is the minimum field width and,
131: if negative,
132: means left justified.
133: .I F2
134: is the number of digits that are converted after the decimal place.
135: The first unconverted digit has suffered decimal rounding.
136: The
137: .B f
138: verb produces output of the form
139: .RB [ - ] digits [ .digits\fR].
140: .B e
141: conversion appends an exponent
142: .BR e [ - ] digits .
143: The
144: .B g
145: verb will output the arg in either
146: .B e
147: or
148: .B f
149: with the goal of producing the smallest output.
150: .PP
151: The
152: .B s
153: verb copies a string
154: (pointer to character)
155: to the output.
156: The number of characters copied
157: .RI ( n )
158: is the minimum
159: of the size of the string and
160: .IR f2 .
161: These
162: .I n
163: characters are justified within a field of
164: .I f1
165: characters as described above.
166: .PP
167: The
168: .B c
169: verb copies a single character (int)
170: justified within a field of
171: .I f1
172: characters as described above.
173: .PP
174: .I Fmtinstall
175: is used to install your own conversions and flags.
176: .I Fn
177: should be declared as
178: .EX
179: int fn(o, f1, f2, f3)
180: void *o;
181: int f1, f2, f3;
182: .EE
183: .I Fn
184: is passed a pointer
185: .I o
186: to whatever argument appears in
187: the list to
188: .IR print .
189: .I Fn
190: should return the size of the argument in bytes so
191: .I print
192: can skip over it.
193: .I F1
194: and
195: .I f2
196: are the decoded numbers in the conversion.
197: A missing
198: .I f1
199: is denoted by the value zero.
200: A missing
201: .I f2
202: is denoted by a negative number.
203: .I F3
204: is the logical or of all the
205: flags seen in the conversion.
206: If
207: .I c
208: is a flag,
209: .I fn
210: should return a negative number
211: that is negated and then logically
212: .IR or ed
213: with any other flags
214: and ultimately
215: passed to a conversion routine.
216: All interpretation of
217: .IR f1 ,
218: .IR f2 ,
219: and
220: .I f3
221: is left up to the conversion routine.
222: The standard flags are
223: .LR h (2),
224: .LR l (1),
225: and
226: .LR u (4).
227: .PP
228: .I Sprint
229: is designed to be recursive in order to
230: help prepare output in custom conversion routines.
231: .PP
232: The output of any conversion routine must be passed through
233: .IR strconv .
234: .I S
235: is the character string,
236: .I f1
237: and
238: .I f2
239: have the same meaning as above.
240: .PP
241: .I Printcol
242: indicates the position of the next output character.
243: Tabs, backspaces and carriage returns are interpreted appropriately.
244: .SH EXAMPLES
245: This adds a verb to print complex numbers.
246: .EX
247: typedef struct {
248: double r, i;
249: } complex;
250: complex x = { 1.5, -2.3 };
251: int Xconv();
252:
253: main()
254: {
255:
256: fmtinstall('X', Xconv);
257: print("x = %X\en", x);
258: }
259:
260: Xconv(o, f1, f2, f3)
261: complex *o;
262: {
263: char str[50];
264:
265: sprint(str, "(%g,%g)", o->r, o->i);
266: strconv(str, f1, f2);
267: return(sizeof(complex));
268: }
269: .EE
270: .SH SEE ALSO
271: .IR fio (3),
272: .IR printf (3)
273: .SH BUGS
274: There are internal buffers which may overflow silently.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.