diff options
Diffstat (limited to 'man/man3/fmtinstall.html')
| -rw-r--r-- | man/man3/fmtinstall.html | 339 |
1 files changed, 0 insertions, 339 deletions
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 @@ -<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> |