term% ls -F
term% cat index.txt
PRINT(2)                      System Calls Manual                     PRINT(2)

       print, fprint, sprint, snprint, fmtinstall, strconv, Strconv, numbconv,
       fltconv, doprint - print formatted output

       #include <u.h>
       #include <libc.h>

       int   print(char *format, ...)

       int   fprint(int fd, char *format, ...)

       int   sprint(char *s, char *format, ...)

       int   snprint(char *s, int len, char *format, ...)

       int   fmtinstall(int c, int (*f)(void*, Fconv*))

       void  strconv(char *s, Fconv *fp)

       void  Strconv(Rune *s, Fconv *fp)

       int   numbconv(void *o, Fconv *fp)

       int   fltconv(double f, Fconv *fp)

       char* doprint(char *s, char *es, char *format, void *argp)

       extern int printcol;

       Print writes text to the standard output.  Fprint writes to  the  named
       output file descriptor; a buffered form is described in bio(2).  Sprint
       places text followed by the NUL character  (\0)  in  consecutive  bytes
       starting  at  s;  it is the user's responsibility to ensure that enough
       storage is available.  Each function returns the number of bytes trans‐
       mitted  (not  including  the  NUL in the case of sprint), or a negative
       value if an output error was encountered.  Snprint is like  sprint  but
       will not place more than len bytes in s.

       Each  of these functions converts, formats, and prints its trailing ar‐
       guments under control of a format  string.   The  format  contains  two
       types of objects: plain characters, which are simply copied to the out‐
       put stream, and conversion specifications, each  of  which  results  in
       fetching of zero or more arguments.  The results are undefined if there
       are arguments of the wrong type or too few arguments  for  the  format.
       If  the  format  is exhausted while arguments remain, the excess is ig‐

       Each conversion specification has the following format:

              % [flags] verb

       The verb is a single character and each flag is a single character or a
       (decimal)  numeric  string.  Up to two numeric strings may be used; the
       first is called f1, the second f2.  A period can be  used  to  separate
       them,  and if the period is present then f1 and f2 are taken to be zero
       if missing, otherwise they are `omitted'.  Either or both of  the  num‐
       bers may be replaced with the character *, meaning that the actual num‐
       ber will be obtained from the argument list as an integer.   The  flags
       and numbers are arguments to the verb described below.

       The numeric verbs d, o, x, and X format their arguments in decimal, oc‐
       tal, hexadecimal, and upper  case  hexadecimal.   Each  interprets  the
       flags  h,  l, u, #, and - to mean short, long, unsigned, alternate for‐
       mat, and left justified.  If neither short nor long is specified,  then
       the argument is an int.  If unsigned is specified, then the argument is
       interpreted as a positive number and no sign is output.  If two l flags
       are  given,  then  the  argument is interpreted as a vlong (a 4-byte or
       sometimes 8-byte integer).  If f2 is not omitted, the number is  padded
       on  the  left with zeros until at least f2 digits appear.  Then, if al‐
       ternate format is specified, for o conversion, the number  is  preceded
       by a 0 if it doesn't already begin with one; for x conversion, the num‐
       ber is preceded by 0x; for X conversion, the number is preceded by  0X.
       Finally,  if  f1  is  not omitted, the number is padded on the left (or
       right, if left justification is specified) with enough blanks  to  make
       the field at least f1 characters long.

       The  floating  point  verbs  f,  e, E, g, and G take a double argument.
       Each interprets the flags +, -, and # to mean always print a sign, left
       justified, and alternate format.  F1 is the minimum field width and, if
       the converted value takes up less than f1 characters, it is  padded  on
       the left (or right, if `left justified') with spaces.  F2 is the number
       of digits that are converted after the decimal place for e,  E,  and  f
       conversions,  and  f2 is the maximum number of significant digits for g
       and G conversions.  The f verb produces  output  of  the  form  [-]dig‐
       its[.digits].   E conversion appends an exponent E[-]digits, and e con‐
       version appends an exponent e[-]digits.  The g verb will output the ar‐
       gument in either e or f with the goal of producing the smallest output.
       Also, trailing zeros are omitted from the fraction part of the  output,
       and a trailing decimal point appears only if it is followed by a digit.
       The G verb is similar, but uses E format instead of e.  When  alternate
       format  is  specified,  the result will always contain a decimal point,
       and for g and G conversions, trailing zeros are not removed.

       The s verb copies a string (pointer to char) to the output.  The number
       of  characters  copied (n) is the minimum of the size of the string and
       f2.  These n characters are justified within a field of  f1  characters
       as  described  above.   The  S  verb  is similar, but it interprets its
       pointer as an array of runes (see utf(6)); the runes are  converted  to
       UTF before output.

       The  c  verb  copies a single char (promoted to int) justified within a
       field of f1 characters as described above.  The C verb is similar,  but
       works on runes.

       The r verb takes no arguments; it copies the error string returned by a
       call to errstr(2).

       Fmtinstall is used to install custom verbs and flags labeled by charac‐
       ter c, must have value less than 512.  Fn should be declared as

              int   fn(void *o, Fconv *fp)

       Fn  is passed a pointer o to whatever argument appears next in the list
       to print.  Fp->chr is the flag or verb character  to  cause  fn  to  be
       called.   In fn, fp->f1 and fp->f2 are the decoded flags in the conver‐
       sion.  A missing fp->f1 is denoted by the value zero.  A missing fp->f2
       is  denoted  by a negative number.  Fp->f3 is the bitwise OR of all the
       flags seen since the most recent The standard flags values are: 1  (+),
       2  (-),  4  (#),  8  (l), 16 (h), 32 (u), and 64 (ll).  If fp->chr is a
       verb, fn should return the size of the argument in bytes so  print  can
       skip over it.  If fp->chr is a flag, fn should return a negative value:
       the negation of one of the above flag values, or some otherwise  unused
       power of two.  All interpretation of fp->f1, fp->f2, and fp->f3 is left
       up to the conversion routine.  Fmtinstall returns 0 if the installation
       succeeds, -1 if it fails.

       Sprint  and  snprint are re-entrant; they may be called to help prepare
       output in custom conversion routines.

       The function strconv formats a UTF string.  S is the string, fp has the
       same  meaning  as  above.   The  strconv routine interprets the flag in
       fp->f3 as left-justification.  The function Strconv (with a capital  S)
       is  like strconv, but its input is a rune string, which is converted to
       UTF on output.

       Printcol indicates the position of the next  output  character.   Tabs,
       backspaces and carriage returns are interpreted appropriately.

       Numbconv is used to implement the integer verbs; its arguments are like
       those of the function argument to fmtinstall.  Fltconv is used  to  im‐
       plement  the floating verbs.  Its arguments are like those of the func‐
       tion argument to fmtinstall, except that the first argument is the dou‐
       ble  itself rather than a pointer to it.  Both numbconv and fltconv use
       strconv to put their results into the current print buffer.

       One of strconv, Strconv, or numbconv must be called to produce  output;
       no other routine puts characters in the output buffer.

       Doprint formats the arguments starting at argp into the buffer starting
       at s, but it writes no characters after the address es.  It  returns  a
       pointer to the NUL terminating the formatted string.

       In  Alef,  Fconv  is  called Printspec and the arguments to strconv are

       This function prints an error message with a variable number  of  argu‐
       ments and then quits.

              void fatal(char *msg, ...)
                    char buf[1024], *out;

                    out = doprint(buf, buf+sizeof(buf), "Fatal error: ");
                    out = doprint(out, buf+sizeof(buf), msg, (&msg+1));
                    write(2, buf, out-buf);
                    exits("fatal error");

       This example adds a verb to print complex numbers.

              struct {
                    double      r, i;
              } Complex;

              Xconv(void *v, Fconv *fp)
                    char str[50];
                    Complex *o;

                    o = v;
                    sprint(str, "(%g,%g)", o->r, o->i);
                    strconv(str, fp);

                    Complex x = (Complex){ 1.5, -2.3 };

                    fmtinstall('X', Xconv);
                    print("x = %X\n", x);


       fprintf(2), utf(6), errstr(2)

       Print and fprint set errstr.

       The formatting is close to that specified for ANSI fprintf(2); the dif‐
       ferences are:

              the - flag doesn't work

              u is a flag here instead of a verb

              X conversion doesn't use upper case A-F for digits ten  to  fif‐

              there are no 0 or space flags here

              there are no P or n verbs here

       Also,  and  distinctly not a bug, print and friends generate UTF rather
       than ASCII.