339 lines
17 KiB
HTML
339 lines
17 KiB
HTML
<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>
|