11 fmtinstall, dofmt, fmtprint, fmtvprint, fmtstrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush \- support for user-defined print formats and output routines
17 .ta \w' 'u +\w' 'u +\w' 'u +\w' 'u +\w' 'u
18 typedef struct Fmt Fmt;
20 void *start; /* of buffer */
21 void *to; /* current place in the buffer */
22 void *stop; /* end of the buffer; overwritten if flush fails */
23 int (*flush)(Fmt*); /* called when to == stop */
24 void *farg; /* to make flush a closure */
25 int nfmt; /* num chars formatted so far */
26 va_list args; /* args passed to dofmt */
27 int r; /* % format character */
35 FmtLeft = FmtWidth << 1,
36 FmtPrec = FmtLeft << 1,
37 FmtSharp = FmtPrec << 1,
38 FmtSpace = FmtSharp << 1,
39 FmtSign = FmtSpace << 1,
40 FmtZero = FmtSign << 1,
41 FmtUnsigned = FmtZero << 1,
42 FmtShort = FmtUnsigned << 1,
43 FmtLong = FmtShort << 1,
44 FmtVLong = FmtLong << 1,
45 FmtComma = FmtVLong << 1,
46 FmtByte = FmtComma << 1,
47 FmtLDouble = FmtByte << 1,
49 FmtFlag = FmtLDouble << 1
58 int fmtfdinit(Fmt *f, int fd, char *buf, int nbuf);
61 int fmtfdflush(Fmt *f);
64 int fmtstrinit(Fmt *f);
67 char* fmtstrflush(Fmt *f);
70 int fmtinstall(int c, int (*fn)(Fmt*));
73 int dofmt(Fmt *f, char *fmt);
76 int fmtprint(Fmt *f, char *fmt, ...);
79 int fmtvprint(Fmt *f, char *fmt, va_list v);
82 int fmtrune(Fmt *f, int r);
85 int fmtstrcpy(Fmt *f, char *s);
87 The interface described here allows the construction of custom
89 verbs and output routines.
90 In essence, they provide access to the workings of the formatted print code.
94 suite maintains its state with a data structure called
98 or its relatives initializes a
100 structure, passes it to subsidiary routines to process the output,
101 and finishes by emitting any saved state recorded in the
105 are unimportant to outside users, except insofar as the general
106 design influences the interface.
110 the verb being processed, its precision and width,
111 and buffering parameters.
112 Most important, it also records a
114 routine that the library will call if a buffer overflows.
115 When printing to a file descriptor, the flush routine will
116 emit saved characters and reset the buffer; when printing
117 to an allocated string, it will resize the string to receive more output.
118 The flush routine is nil when printing to fixed-size buffers.
119 User code need never provide a flush routine; this is done internally
121 .SS Custom output routines
122 To write a custom output routine, such as an error handler that
123 formats and prints custom error messages, the output sequence can be run
124 from outside the library using the routines described here.
125 There are two main cases: output to an open file descriptor
126 and output to a string.
128 To write to a file descriptor, call
130 to initialize the local
134 giving the file descriptor
144 to generate the output.
145 These behave just like
151 except that the characters are buffered until
154 A typical example of this sequence appears in the Examples section.
156 The same basic sequence applies when outputting to an allocated string:
165 to generate the output.
168 will return the allocated string, which should be freed after use.
169 Regardless of the output style or type,
173 generates the characters.
174 .SS Custom format verbs
176 is used to install custom verbs and flags labeled by character
178 which may be any non-zero Unicode character.
180 should be declared as
187 is the flag or verb character to cause
194 are the width and precision, and
196 the decoded flags for the verb (see
198 for a description of these items).
199 The standard flag values are:
227 identify whether a width and precision were specified.
230 is passed a pointer to the
232 structure recording the state of the output.
235 is a verb (rather than a flag),
239 to fetch its argument from the list,
240 then format it, and return zero.
245 should return a negative value:
246 the negation of one of the above flag values, or some otherwise unused power of two.
247 All interpretation of
252 is left up to the conversion routine.
254 returns 0 if the installation succeeds, \-1 if it fails.
260 help prepare output in custom conversion routines.
261 However, these functions clear the width, precision, and flags.
264 is the underlying formatter; it
265 uses the existing contents of
267 and should be called only by sophisticated conversion routines.
268 All these routines return the number of characters
271 Some internal functions may be useful to format primitive types.
272 They honor the width, precision and flags as described in
275 formats a single character
280 All these routines return zero for successful execution.
282 This function prints an error message with a variable
283 number of arguments and then quits.
284 Compared to the corresponding example in
286 this version uses a smaller buffer, will never truncate
287 the output message, but might generate multiple
289 system calls to produce its output.
292 .ta 6n +6n +6n +6n +6n +6n +6n +6n +6n
294 void fatal(char *fmt, ...)
300 fmtfdinit(&f, 1, buf, sizeof buf);
301 fmtprint(&f, "fatal: ");
303 fmtvprint(&f, fmt, arg);
307 exits("fatal error");
311 This example adds a verb to print complex numbers.
324 c = va_arg(f->args, Complex);
325 return fmtprint(f, "(%g,%g)", c.r, c.i);
335 fmtinstall('X', Xfmt);
336 print("x = %X\en", x);
342 This formatted print library originally
343 appeared as part of the Plan 9 C library.
345 The Plan 9 version supports Unicode strings and produces UTF output.
346 This version assumes that characters are always represented by 1-byte values.
