ERRSTR(3)                                               ERRSTR(3)

     NAME
          errstr, rerrstr, werrstr - description of last system call
          error

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

          int errstr(char *err, uint nerr)

          void rerrstr(char *err, uint nerr)

          void werrstr(char *fmt, ...)

     DESCRIPTION
          When a system call fails it returns -1 and records a null
          terminated string describing the error in a per-process
          buffer.  Errstr swaps the contents of that buffer with the
          contents of the array err. Errstr will write at most nerr
          bytes into err; if the per-process error string does not
          fit, it is silently truncated at a UTF character boundary.
          The returned string is NUL-terminated.  Usually errstr will
          be called with an empty string, but the exchange property
          provides a mechanism for libraries to set the return value
          for the next call to errstr.

          The per-process buffer is ERRMAX bytes long.  Any error
          string provided by the user will be truncated at ERRMAX-1
          bytes.  ERRMAX is defined in <libc.h>.

          If no system call has generated an error since the last call
          to errstr with an empty string, the result is an empty
          string.

          The verb r in print(3) calls errstr and outputs the error
          string.

          Rerrstr reads the error string but does not modify the per-
          process buffer, so a subsequent errstr will recover the same
          string.

          Werrstr takes a print style format as its argument and uses
          it to format a string to pass to errstr. The string returned
          from errstr is discarded.

          The error string is maintained in parallel with the Unix
          error number errno. Changing errno will reset the error
          string, and changing the error string via errstr or werrstr
          will reset errno.

     ERRSTR(3)                                               ERRSTR(3)

     SOURCE
          /src/lib9/errstr.c

     DIAGNOSTICS
          Errstr always returns 0.

     SEE ALSO
          intro(3), perror(3)

     BUGS
          The implementation sets errno to the (somewhat arbitrary)
          constant 0x19283745 when the error string is valid.  When
          errno is set to other values, the error string is synthe-
          sized using strerror(3).