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



NAME
       print,  fprint,  sprint,  snprint, seprint, smprint, runesprint, runes‐
       nprint, runeseprint, runesmprint,  vfprint,  vsnprint,  vseprint,  vsm‐
       print,  runevsnprint, runevseprint, runevsmprint - print formatted out‐
       put

SYNOPSIS
       #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, ...)

       char* seprint(char *s, char *e, char *format, ...)

       char* smprint(char *format, ...)

       int   runesprint(Rune *s, char *format, ...)

       int   runesnprint(Rune *s, int len, char *format, ...)

       Rune* runeseprint(Rune *s, Rune *e, char *format, ...)

       Rune* runesmprint(char *format, ...)

       int   vfprint(int fd, char *format, va_list v)

       int   vsnprint(char *s, int len, char *format, va_list v)

       char* vseprint(char *s, char *e, char *format, va_list v)

       char* vsmprint(char *format, va_list v)

       int   runevsnprint(Rune *s, int len, char *format, va_list v)

       Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v)

       Rune* runevsmprint(Rune *format, va_list v)

DESCRIPTION
       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.
       Its  result  is  always  NUL-terminated and holds the maximal number of
       complete UTF-8 characters that  can  fit.   Seprint  is  like  snprint,
       except that the end is indicated by a pointer e rather than a count and
       the return value points to the terminating NUL of the resulting string.
       Smprint is like sprint, except that it prints into and returns a string
       of the required length, which is allocated by malloc(2).

       The routines runesprint, runesnprint, runeseprint, and runesmprint  are
       the same as sprint, snprint, seprint and smprint except that their out‐
       put is rune strings instead of byte strings.

       Finally, the routines vfprint, vsnprint,  vseprint,  vsmprint,  runevs‐
       nprint,  runevseprint, and runevsmprint are like their v-less relatives
       except they take as arguments a  va_list  parameter,  so  they  can  be
       called  within a variadic function.  The Example section shows a repre‐
       sentative usage.

       Each of these functions converts,  formats,  and  prints  its  trailing
       arguments  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
       ignored.

       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 width, the second precision.  A period can be used to
       separate them, and if the period is present then  width  and  precision
       are  taken to be zero if missing, otherwise they are `omitted'.  Either
       or both of the numbers may be replaced with the  character  *,  meaning
       that  the  actual  number 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, b, x, and X format their arguments in decimal,
       octal, binary, hexadecimal, and upper case  hexadecimal.   Each  inter‐
       prets  the flags 0, h, hh, l, u, +, -, ,, and # to mean pad with zeros,
       short, byte, long, unsigned, always print a sign, left justified,  com‐
       mas  every three digits, and alternate format.  Also, a space character
       in the flag position is like +, but prints a space instead  of  a  plus
       sign  for non-negative values.  If neither short nor long is specified,
       then the argument is an int.  If unsigned is specified, then the  argu‐
       ment 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 (usually
       an  8-byte,  sometimes a 4-byte integer).  If precision is not omitted,
       the number is padded on the left with zeros until  at  least  precision
       digits  appear.   Then, if alternate format is specified, for o conver‐
       sion, the number is preceded by a 0 if it doesn't  already  begin  with
       one;  for x conversion, the number is preceded by 0x; for X conversion,
       the number is preceded by 0X.  Finally, if width is  not  omitted,  the
       number is padded on the left (or right, if left justification is speci‐
       fied) with enough blanks to make the field at  least  width  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.  Width is the minimum field width and,
       if the converted value takes up  less  than  width  characters,  it  is
       padded on the left (or right, if `left justified') with spaces.  Preci‐
       sion is the number of digits that are converted after the decimal place
       for  e,  E,  and  f conversions, and precision is the maximum number of
       significant digits for g and G conversions.  The f verb produces output
       of  the  form  [-]digits[.digits].   E  conversion  appends an exponent
       E[-]digits, and e conversion appends an  exponent  e[-]digits.   The  g
       verb will output the argument in either e or f with the goal of produc‐
       ing 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 nul-terminated string (pointer to char) to the out‐
       put.  The number of characters copied (n) is the minimum of the size of
       the  string  and  precision.  These n characters are justified within a
       field of width characters as described above.  If a precision is given,
       it  is safe for the string not to be nul-terminated as long as it is at
       least precision characters (not bytes!) long.  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  width characters as described above.  The C verb is similar,
       but works on runes.

       The p verb formats a single pointer or pointer-sized integer  (uintptr,
       see intro(2)) in hexadecimal.

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

       Custom verbs may be installed using fmtinstall(2).

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

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

                    out = seprint(buf, buf+sizeof(buf), "Fatal error: ");
                    va_start(arg, msg);
                    out = vseprint(out, buf+sizeof(buf), msg, arg);
                    va_end(arg);
                    write(2, buf, out-buf);
                    exits("fatal error");
              }

SOURCE
       /sys/src/libc/fmt

SEE ALSO
       fmtinstall(2), fprintf(2), utf(6), errstr(2)

DIAGNOSTICS
       Routines that write to a file descriptor or call malloc set errstr.

BUGS
       The formatting is close to that specified for ANSI fprintf(2); the main
       difference is that b is not in ANSI and u is a flag here instead  of  a
       verb.   Also,  and distinctly not a bug, print and friends generate UTF
       rather than ASCII.

       There is no runeprint, runefprint, etc. because  runes  are  byte-order
       dependent  and  should  not  be written directly to a file; use the UTF
       output of print or fprint instead.   Also,  sprint  is  deprecated  for
       safety  reasons; use snprint, seprint, or smprint instead.  Safety also
       precludes the existence of runesprint.



                                                                      PRINT(2)