diff options
Diffstat (limited to 'man/man3/fmtinstall.html')
| -rw-r--r-- | man/man3/fmtinstall.html | 339 |
1 files changed, 339 insertions, 0 deletions
diff --git a/man/man3/fmtinstall.html b/man/man3/fmtinstall.html new file mode 100644 index 00000000..848c1333 --- /dev/null +++ b/man/man3/fmtinstall.html @@ -0,0 +1,339 @@ +<head> +<title>fmtinstall(3) - Plan 9 from User Space</title> +<meta content="text/html; charset=utf-8" http-equiv=Content-Type> +</head> +<body bgcolor=#ffffff> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=10><td> +<tr><td width=20><td> +<tr><td width=20><td><b>FMTINSTALL(3)</b><td align=right><b>FMTINSTALL(3)</b> +<tr><td width=20><td colspan=2> + <br> +<p><font size=+1><b>NAME </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + fmtinstall, dofmt, dorfmt, fmtprint, fmtvprint, fmtrune, fmtstrcpy, + fmtrunestrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush, + runefmtstrinit, runefmtstrflush, errfmt – support for user-defined + print formats and output routines<br> + +</table> +<p><font size=+1><b>SYNOPSIS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>#include <u.h><br> + #include <libc.h> + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>typedef struct Fmt Fmt;<br> + struct Fmt{<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + uchar runes; /* output buffer is runes or chars? */<br> + void *start; /* of buffer */<br> + void *to; /* current place in the buffer */<br> + void *stop; /* end of the buffer; overwritten if flush fails */<br> + int (*flush)(Fmt*);/* called when to == stop */<br> + void *farg; /* to make flush a closure */<br> + int nfmt; /* num chars formatted so far */<br> + va_list args; /* args passed to dofmt */<br> + int r; /* % format Rune */<br> + int width;<br> + int prec;<br> + ulong flags;<br> + + </table> + };<br> + enum{<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + FmtWidth = 1,<br> + FmtLeft = FmtWidth << 1,<br> + FmtPrec = FmtLeft << 1,<br> + FmtSharp = FmtPrec << 1,<br> + FmtSpace = FmtSharp << 1,<br> + FmtSign = FmtSpace << 1,<br> + FmtZero = FmtSign << 1,<br> + FmtUnsigned = FmtZero << 1,<br> + FmtShort = FmtUnsigned << 1,<br> + FmtLong = FmtShort << 1,<br> + FmtVLong = FmtLong << 1,<br> + FmtComma = FmtVLong << 1,<br> + FmtFlag = FmtComma << 1<br> + + </table> + };<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + int fmtfdinit(Fmt *f, int fd, char *buf, int nbuf); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fmtfdflush(Fmt *f); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fmtstrinit(Fmt *f); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>char* fmtstrflush(Fmt *f); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int runefmtstrinit(Fmt *f); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>Rune* runefmtstrflush(Fmt *f);<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fmtinstall(int c, int (*fn)(Fmt*)); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int dofmt(Fmt *f, char *fmt); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int dorfmt(Fmt*, Rune *fmt); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fmtprint(Fmt *f, char *fmt, ...); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fmtvprint(Fmt *f, char *fmt, va_list v); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fmtrune(Fmt *f, int r); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fmtstrcpy(Fmt *f, char *s); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int fmtrunestrcpy(Fmt *f, Rune *s); + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>int errfmt(Fmt *f);<br> + </font></tt> +</table> +<p><font size=+1><b>DESCRIPTION </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + The interface described here allows the construction of custom + <a href="../man3/print.html"><i>print</i>(3)</a> verbs and output routines. In essence, they provide access + to the workings of the formatted print code. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The <a href="../man3/print.html"><i>print</i>(3)</a> suite maintains its state with a data structure called + <tt><font size=+1>Fmt</font></tt>. A typical call to <a href="../man3/print.html"><i>print</i>(3)</a> or its relatives initializes a + <tt><font size=+1>Fmt</font></tt> structure, passes it to subsidiary routines to process the + output, and finishes by emitting any saved state recorded in the + <tt><font size=+1>Fmt</font></tt>. The details of the <tt><font size=+1>Fmt</font></tt> are unimportant to outside users, + except + insofar as the general design influences the interface. The <tt><font size=+1>Fmt</font></tt> + 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 <i>flush</i> 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.<br> + <p><font size=+1><b>Custom output routines </b></font><br> + 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. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + To write to a file descriptor, call <i>fmtfdinit</i> to initialize the + local <tt><font size=+1>Fmt</font></tt> structure <i>f</i>, giving the file descriptor <i>fd</i>, the buffer + <i>buf</i>, and its size <i>nbuf</i>. Then call <i>fmtprint</i> or <i>fmtvprint</i> to generate + the output. These behave like <tt><font size=+1>fprint</font></tt> (see <a href="../man3/print.html"><i>print</i>(3)</a>) or <tt><font size=+1>vfprint</font></tt> + except that the characters are buffered until <i>fmtfdflush</i> is called + and the return value is either 0 or –1. A typical example of this + sequence appears in the Examples section. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The same basic sequence applies when outputting to an allocated + string: call <i>fmtstrinit</i> to initialize the <tt><font size=+1>Fmt</font></tt>, then call <i>fmtprint</i> + and <i>fmtvprint</i> to generate the output. Finally, <i>fmtstrflush</i> will + return the allocated string, which should be freed after use. + To output to a rune string, use <i>runefmtstrinit</i> and <i>runefmtstrflush</i>. + Regardless of the output style or type, <i>fmtprint</i> or <i>fmtvprint</i> + generates the characters.<br> + <p><font size=+1><b>Custom format verbs </b></font><br> + <i>Fmtinstall</i> is used to install custom verbs and flags labeled by + character <i>c</i>, which may be any non-zero Unicode character. <i>Fn</i> should + be declared as<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>int fn(Fmt*)<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + <i>Fp</i><tt><font size=+1>−>r</font></tt> is the flag or verb character to cause <i>fn</i> to be called. In + <i>fn</i>, <i>fp</i><tt><font size=+1>−>width</font></tt><i>, fp</i><tt><font size=+1>−>prec</font></tt> are the width and precision, and <i>fp</i><tt><font size=+1>−>flags</font></tt> + the decoded flags for the verb (see <a href="../man3/print.html"><i>print</i>(3)</a> for a description + of these items). The standard flag values are: <tt><font size=+1>FmtSign</font></tt> (<tt><font size=+1>+</font></tt>), <tt><font size=+1>FmtLeft</font></tt> + (<tt><font size=+1>−</font></tt>), <tt><font size=+1>FmtSpace</font></tt> (<tt><font size=+1>' '</font></tt>), <tt><font size=+1>FmtSharp</font></tt> (<tt><font size=+1>#</font></tt>), + <tt><font size=+1>FmtComma</font></tt> (<tt><font size=+1>,</font></tt>), <tt><font size=+1>FmtLong</font></tt> (<tt><font size=+1>l</font></tt>), <tt><font size=+1>FmtShort</font></tt> (<tt><font size=+1>h</font></tt>), <tt><font size=+1>FmtUnsigned</font></tt> (<tt><font size=+1>u</font></tt>), and + <tt><font size=+1>FmtVLong</font></tt> (<tt><font size=+1>ll</font></tt>). The flag bits <tt><font size=+1>FmtWidth</font></tt> and <tt><font size=+1>FmtPrec</font></tt> identify whether + a width and precision were specified. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Fn</i> is passed a pointer to the <tt><font size=+1>Fmt</font></tt> structure recording the state + of the output. If <i>fp</i><tt><font size=+1>−>r</font></tt> is a verb (rather than a flag), <i>fn</i> should + use <tt><font size=+1>Fmt−>args</font></tt> to fetch its argument from the list, then format + it, and return zero. If <i>fp</i><tt><font size=+1>−>r</font></tt> is a flag, <i>fn</i> should return one. + All interpretation of <i>fp</i><tt><font size=+1>−>width</font></tt>, <i>fp</i><tt><font size=+1>−>prec</font></tt>, and <i>fp-></i><tt><font size=+1>flags</font></tt> is + left up to the conversion routine. <i>Fmtinstall</i> returns 0 if the + installation succeeds, –1 if it fails. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Fmtprint</i> and <i>fmtvprint</i> 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. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + The functions <i>dofmt</i> and <i>dorfmt</i> are the underlying formatters; + they use the existing contents of <tt><font size=+1>Fmt</font></tt> and should be called only + by sophisticated conversion routines. These routines return the + number of characters (bytes of UTF or runes) produced. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + Some internal functions may be useful to format primitive types. + They honor the width, precision and flags as described in <a href="../man3/print.html"><i>print</i>(3)</a>. + <i>Fmtrune</i> formats a single character <tt><font size=+1>r</font></tt>. <i>Fmtstrcpy</i> formats a string + <tt><font size=+1>s</font></tt>; <i>fmtrunestrcpy</i> formats a rune string <tt><font size=+1>s</font></tt>. <i>Errfmt</i> 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.<br> + +</table> +<p><font size=+1><b>EXAMPLES </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + This function prints an error message with a variable number of + arguments and then quits. Compared to the corresponding example + in <a href="../man3/print.html"><i>print</i>(3)</a>, this version uses a smaller buffer, will never truncate + the output message, but might generate multiple <tt><font size=+1>write</font></tt> system calls + to produce its output. + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>#pragma varargck argpos error 1<br> + void fatal(char *fmt, ...)<br> + {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Fmt f;<br> + char buf[64];<br> + va_list arg;<br> + fmtfdinit(&f, 1, buf, sizeof buf);<br> + fmtprint(&f, "fatal: ");<br> + va_start(arg, fmt);<br> + fmtvprint(&f, fmt, arg);<br> + va_end(arg);<br> + fmtprint(&f, "\n");<br> + fmtfdflush(&f);<br> + exits("fatal error");<br> + + </table> + }<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + This example adds a verb to print complex numbers.<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>typedef<br> + struct {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + double r, i;<br> + + </table> + } Complex;<br> + #pragma varargck type "X" Complex<br> + int<br> + Xfmt(Fmt *f)<br> + {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Complex c;<br> + c = va_arg(f−>args, Complex);<br> + return fmtprint(f, "(%g,%g)", c.r, c.i);<br> + + </table> + }<br> + main(...)<br> + {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + Complex x = (Complex){ 1.5, −2.3 };<br> + fmtinstall('X', Xfmt);<br> + print("x = %X\n", x);<br> + + </table> + }<br> + </font></tt> + </table> + +</table> +<p><font size=+1><b>SOURCE </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>/usr/local/plan9/src/lib9/fmt<br> + </font></tt> +</table> +<p><font size=+1><b>SEE ALSO </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <a href="../man3/print.html"><i>print</i>(3)</a>, <a href="../man7/utf.html"><i>utf</i>(7)</a>, <a href="../man3/errstr.html"><i>errstr</i>(3)</a><br> + +</table> +<p><font size=+1><b>DIAGNOSTICS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + These routines return negative numbers or nil for errors and set + <i>errstr</i>.<br> + +</table> + +<td width=20> +<tr height=20><td> +</table> +<!-- TRAILER --> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=15><td width=10><td><td width=10> +<tr><td><td> +<center> +<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> +</center> +</table> +<!-- TRAILER --> +</body></html> |