ERRSTR(2)                                               ERRSTR(2)

     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(2) 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.

     SOURCE
          /sys/src/libc/9syscall
          /sys/src/libc/9sys/rerrstr.c
          /sys/src/libc/9sys/werrstr.c

     Page 1                       Plan 9             (printed 3/19/24)

     ERRSTR(2)                                               ERRSTR(2)

     DIAGNOSTICS
          Errstr always returns 0.

     SEE ALSO
          intro(2), perror(2)

     Page 2                       Plan 9             (printed 3/19/24)