fmtinstall man page on Plan9

Man page or keyword search:  
man Server   549 pages
apropos Keyword Search (all sections)
Output format
Plan9 logo
[printable version]

FMTINSTALL(2)							 FMTINSTALL(2)

NAME
       fmtinstall,  dofmt,  dorfmt,  fmtprint,	fmtvprint, fmtrune, fmtstrcpy,
       fmtrunestrcpy, fmtfdinit, fmtfdflush, fmtstrinit, fmtstrflush, runefmt‐
       strinit,	 runefmtstrflush, errfmt - support for user-defined print for‐
       mats 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(2)
       verbs  and  output  routines.   In  essence, they provide access to the
       workings of the formatted print code.

       The print(2) suite maintains its state with  a  data  structure	called
       Fmt.   A	 typical  call	to print(2) 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 gen‐
       eral design influences the interface.  The Fmt records whether the out‐
       put 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 char‐
       acters 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(2)) 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 charac‐
       ter 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(2) 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  interpre‐
       tation  of fp->width, fp->prec, and fp->flags is left up to the conver‐
       sion 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.  These functions will preserve  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(2).  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.  Con‐
       version	routines  that call these functions will work properly regard‐
       less of whether the output is bytes or runes.

       8c(1) describes the C directive #pragma varargck that can  be  used  to
       provide type-checking for custom print verbs and output routines.

EXAMPLES
       This  function  prints an error message with a variable number of argu‐
       ments and  then	quits.	 Compared  to  the  corresponding  example  in
       print(2),  this	version uses a smaller buffer, will never truncate the
       output message, but might generate multiple write system calls to  pro‐
       duce its output.

	      #pragma	  varargck    argpos	  fatal 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
       /sys/src/libc/fmt

SEE ALSO
       print(2), utf(6), errstr(2)

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

								 FMTINSTALL(2)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net