From adc93f6097615f16d57e8a24a256302f2144ec4e Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 17:37:50 +0000 Subject: cut out the html - they're going to cause diffing problems. --- man/man3/fmtinstall.html | 339 ----------------------------------------------- 1 file changed, 339 deletions(-) delete mode 100644 man/man3/fmtinstall.html (limited to 'man/man3/fmtinstall.html') diff --git a/man/man3/fmtinstall.html b/man/man3/fmtinstall.html deleted file mode 100644 index 848c1333..00000000 --- a/man/man3/fmtinstall.html +++ /dev/null @@ -1,339 +0,0 @@ - -fmtinstall(3) - Plan 9 from User Space - - - - -
-
-
FMTINSTALL(3)FMTINSTALL(3) -
-
-

NAME
- -
- - fmtinstall, dofmt, dorfmt, fmtprint, fmtvprint, fmtrune, fmtstrcpy, - fmtrunestrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush, - runefmtstrinit, runefmtstrflush, errfmt – support for user-defined - print formats and output routines
- -
-

SYNOPSIS
- -
- - #include <u.h>
- #include <libc.h> -
- - typedef struct Fmt    Fmt;
- struct Fmt{
- -
- - uchar     runes;    /* output buffer is runes or chars? */
- void      *start; /* of buffer */
- void      *to;      /* current place in the buffer */
- void      *stop;    /* end of the buffer; overwritten if flush fails */
- int       (*flush)(Fmt*);/* called when to == stop */
- void      *farg;    /* to make flush a closure */
- int       nfmt;     /* num chars formatted so far */
- va_list args;     /* args passed to dofmt */
- int       r;        /* % format Rune */
- int       width;
- int       prec;
- ulong     flags;
- -
- };
- enum{
- -
- - FmtWidth      = 1,
- FmtLeft       = FmtWidth << 1,
- FmtPrec       = FmtLeft << 1,
- FmtSharp      = FmtPrec << 1,
- FmtSpace      = FmtSharp << 1,
- FmtSign       = FmtSpace << 1,
- FmtZero       = FmtSign << 1,
- FmtUnsigned = FmtZero << 1,
- FmtShort      = FmtUnsigned << 1,
- FmtLong       = FmtShort << 1,
- FmtVLong      = FmtLong << 1,
- FmtComma      = FmtVLong << 1,
- FmtFlag       = FmtComma << 1
- -
- };
- -
- - -
- - int     fmtfdinit(Fmt *f, int fd, char *buf, int nbuf); -
- - int     fmtfdflush(Fmt *f); -
- - int     fmtstrinit(Fmt *f); -
- - char* fmtstrflush(Fmt *f); -
- - int     runefmtstrinit(Fmt *f); -
- - Rune* runefmtstrflush(Fmt *f);
- -
- - int     fmtinstall(int c, int (*fn)(Fmt*)); -
- - int     dofmt(Fmt *f, char *fmt); -
- - int     dorfmt(Fmt*, Rune *fmt); -
- - int     fmtprint(Fmt *f, char *fmt, ...); -
- - int     fmtvprint(Fmt *f, char *fmt, va_list v); -
- - int     fmtrune(Fmt *f, int r); -
- - int     fmtstrcpy(Fmt *f, char *s); -
- - int     fmtrunestrcpy(Fmt *f, Rune *s); -
- - int     errfmt(Fmt *f);
- -
-

DESCRIPTION
- -
- - The interface described here allows the construction of custom - print(3) verbs and output routines. In essence, they provide access - to the workings of the formatted print code. -
- - The print(3) suite maintains its state with a data structure called - Fmt. A typical call to print(3) or its relatives initializes a - Fmt structure, passes it to subsidiary routines to process the - output, and finishes by emitting any saved state recorded in the - Fmt. The details of the Fmt are unimportant to outside users, - except - insofar as the general design influences the interface. The Fmt - records whether the output is in runes or bytes, the verb being - processed, its precision and width, and buffering parameters. - Most important, it also records a flush routine that the library - will call if a buffer overflows. When printing to a file descriptor, - the - flush routine will emit saved characters and reset the buffer; - when printing to an allocated string, it will resize the string - to receive more output. The flush routine is nil when printing - to fixed-size buffers. User code need never provide a flush routine; - this is done internally by the library.
-

Custom output routines
- To write a custom output routine, such as an error handler that - formats and prints custom error messages, the output sequence - can be run from outside the library using the routines described - here. There are two main cases: output to an open file descriptor - and output to a string. -
- - To write to a file descriptor, call fmtfdinit to initialize the - local Fmt structure f, giving the file descriptor fd, the buffer - buf, and its size nbuf. Then call fmtprint or fmtvprint to generate - the output. These behave like fprint (see print(3)) or vfprint - except that the characters are buffered until fmtfdflush is called - and the return value is either 0 or –1. A typical example of this - sequence appears in the Examples section. -
- - The same basic sequence applies when outputting to an allocated - string: call fmtstrinit to initialize the Fmt, then call fmtprint - and fmtvprint to generate the output. Finally, fmtstrflush will - return the allocated string, which should be freed after use. - To output to a rune string, use runefmtstrinit and runefmtstrflush. - Regardless of the output style or type, fmtprint or fmtvprint - generates the characters.
-

Custom format verbs
- Fmtinstall is used to install custom verbs and flags labeled by - character c, which may be any non-zero Unicode character. Fn should - be declared as
- -
- - int     fn(Fmt*)
- -
- - -
- Fp−>r is the flag or verb character to cause fn to be called. In - fn, fp−>width, fp−>prec are the width and precision, and fp−>flags - the decoded flags for the verb (see print(3) for a description - of these items). The standard flag values are: FmtSign (+), FmtLeft - (−), FmtSpace (' '), FmtSharp (#), - FmtComma (,), FmtLong (l), FmtShort (h), FmtUnsigned (u), and - FmtVLong (ll). The flag bits FmtWidth and FmtPrec identify whether - a width and precision were specified. -
- - Fn is passed a pointer to the Fmt structure recording the state - of the output. If fp−>r is a verb (rather than a flag), fn should - use Fmt−>args to fetch its argument from the list, then format - it, and return zero. If fp−>r is a flag, fn should return one. - All interpretation of fp−>width, fp−>prec, and fp->flags is - left up to the conversion routine. Fmtinstall returns 0 if the - installation succeeds, –1 if it fails. -
- - Fmtprint and fmtvprint may be called to help prepare output in - custom conversion routines. However, these functions clear the - width, precision, and flags. Both functions return 0 for success - and –1 for failure. -
- - The functions dofmt and dorfmt are the underlying formatters; - they use the existing contents of Fmt and should be called only - by sophisticated conversion routines. These routines return the - number of characters (bytes of UTF or runes) produced. -
- - Some internal functions may be useful to format primitive types. - They honor the width, precision and flags as described in print(3). - Fmtrune formats a single character r. Fmtstrcpy formats a string - s; fmtrunestrcpy formats a rune string s. Errfmt formats the system - error string. All these routines return zero for - successful execution. Conversion routines that call these functions - will work properly regardless of whether the output is bytes or - runes.
- -

-

EXAMPLES
- -
- - This function prints an error message with a variable number of - arguments and then quits. Compared to the corresponding example - in print(3), this version uses a smaller buffer, will never truncate - the output message, but might generate multiple write system calls - to produce its output. - -
- - #pragma    varargck argpos    error     1
- void fatal(char *fmt, ...)
- {
- -
- - Fmt f;
- char buf[64];
- va_list arg;
- fmtfdinit(&f, 1, buf, sizeof buf);
- fmtprint(&f, "fatal: ");
- va_start(arg, fmt);
- fmtvprint(&f, fmt, arg);
- va_end(arg);
- fmtprint(&f, "\n");
- fmtfdflush(&f);
- exits("fatal error");
- -
- }
- -
- - -
- This example adds a verb to print complex numbers.
- -
- - typedef
- struct {
- -
- - double    r, i;
- -
- } Complex;
- #pragma    varargck type "X" Complex
- int
- Xfmt(Fmt *f)
- {
- -
- - Complex c;
- c = va_arg(f−>args, Complex);
- return fmtprint(f, "(%g,%g)", c.r, c.i);
- -
- }
- main(...)
- {
- -
- - Complex x = (Complex){ 1.5, −2.3 };
- fmtinstall('X', Xfmt);
- print("x = %X\n", x);
- -
- }
- -
- -
-

SOURCE
- -
- - /usr/local/plan9/src/lib9/fmt
- -
-

SEE ALSO
- -
- - print(3), utf(7), errstr(3)
- -
-

DIAGNOSTICS
- -
- - These routines return negative numbers or nil for errors and set - errstr.
- -
- -

 -
-
- - -
-
-
-Space Glenda -
-
- - -- cgit v1.2.3