1 cfa37a7b 2004-04-10 devnull .TH ERRSTR 3
  2 cfa37a7b 2004-04-10 devnull .SH NAME
  3 cfa37a7b 2004-04-10 devnull errstr, rerrstr, werrstr \- description of last system call error
  4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
  5 cfa37a7b 2004-04-10 devnull .B #include <u.h>
  6 cfa37a7b 2004-04-10 devnull .br
  7 cfa37a7b 2004-04-10 devnull .B #include <libc.h>
  8 cfa37a7b 2004-04-10 devnull .PP
  9 cfa37a7b 2004-04-10 devnull .B
 10 cfa37a7b 2004-04-10 devnull int errstr(char *err, uint nerr)
 11 cfa37a7b 2004-04-10 devnull .PP
 12 cfa37a7b 2004-04-10 devnull .B
 13 cfa37a7b 2004-04-10 devnull void rerrstr(char *err, uint nerr)
 14 cfa37a7b 2004-04-10 devnull .PP
 15 cfa37a7b 2004-04-10 devnull .B
 16 cfa37a7b 2004-04-10 devnull void werrstr(char *fmt, ...)
 17 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
 18 cfa37a7b 2004-04-10 devnull When a system call fails it returns \-1 and
 19 cfa37a7b 2004-04-10 devnull records a null terminated string describing the error in a per-process buffer.
 20 cfa37a7b 2004-04-10 devnull .I Errstr
 21 cfa37a7b 2004-04-10 devnull swaps the contents of that buffer with the contents of the array
 22 cfa37a7b 2004-04-10 devnull .IR err .
 23 cfa37a7b 2004-04-10 devnull .I Errstr
 24 cfa37a7b 2004-04-10 devnull will write at most 
 25 cfa37a7b 2004-04-10 devnull .I nerr
 26 cfa37a7b 2004-04-10 devnull bytes into 
 27 cfa37a7b 2004-04-10 devnull .IR err ;
 28 cfa37a7b 2004-04-10 devnull if the per-process error string does not fit,
 29 cfa37a7b 2004-04-10 devnull it is silently truncated at a UTF character boundary.
 30 cfa37a7b 2004-04-10 devnull The returned string is NUL-terminated.
 31 cfa37a7b 2004-04-10 devnull Usually
 32 cfa37a7b 2004-04-10 devnull .I errstr
 33 cfa37a7b 2004-04-10 devnull will be called with an empty string,
 34 cfa37a7b 2004-04-10 devnull but the exchange property provides a mechanism for
 35 cfa37a7b 2004-04-10 devnull libraries to set the return value for the next call to
 36 cfa37a7b 2004-04-10 devnull .IR errstr .
 37 cfa37a7b 2004-04-10 devnull .PP
 38 cfa37a7b 2004-04-10 devnull The per-process buffer is
 39 cfa37a7b 2004-04-10 devnull .B ERRMAX
 40 cfa37a7b 2004-04-10 devnull bytes long.  Any error string provided by the user will
 41 cfa37a7b 2004-04-10 devnull be truncated at 
 42 cfa37a7b 2004-04-10 devnull .B ERRMAX-1
 43 cfa37a7b 2004-04-10 devnull bytes.
 44 cfa37a7b 2004-04-10 devnull .B ERRMAX
 45 cfa37a7b 2004-04-10 devnull is defined in
 46 cfa37a7b 2004-04-10 devnull .BR <libc.h> .
 47 cfa37a7b 2004-04-10 devnull .PP
 48 cfa37a7b 2004-04-10 devnull If no system call has generated an error since the last call to
 49 cfa37a7b 2004-04-10 devnull .I errstr
 50 cfa37a7b 2004-04-10 devnull with an empty string,
 51 cfa37a7b 2004-04-10 devnull the result is an empty string.
 52 cfa37a7b 2004-04-10 devnull .PP
 53 cfa37a7b 2004-04-10 devnull The verb
 54 cfa37a7b 2004-04-10 devnull .B r
 55 cfa37a7b 2004-04-10 devnull in
 56 d32deab1 2020-08-16 rsc .MR print (3)
 57 cfa37a7b 2004-04-10 devnull calls
 58 cfa37a7b 2004-04-10 devnull .I errstr
 59 cfa37a7b 2004-04-10 devnull and outputs the error string.
 60 cfa37a7b 2004-04-10 devnull .PP
 61 cfa37a7b 2004-04-10 devnull .I Rerrstr
 62 cfa37a7b 2004-04-10 devnull reads the error string but does not modify the per-process buffer, so
 63 cfa37a7b 2004-04-10 devnull a subsequent
 64 cfa37a7b 2004-04-10 devnull .I errstr
 65 cfa37a7b 2004-04-10 devnull will recover the same string.
 66 cfa37a7b 2004-04-10 devnull .PP
 67 cfa37a7b 2004-04-10 devnull .I Werrstr
 68 cfa37a7b 2004-04-10 devnull takes a
 69 cfa37a7b 2004-04-10 devnull .I print
 70 cfa37a7b 2004-04-10 devnull style format as its argument and uses it to format
 71 cfa37a7b 2004-04-10 devnull a string to pass to
 72 cfa37a7b 2004-04-10 devnull .IR errstr .
 73 cfa37a7b 2004-04-10 devnull The string returned from
 74 cfa37a7b 2004-04-10 devnull .I errstr
 75 cfa37a7b 2004-04-10 devnull is discarded.
 76 058b0118 2005-01-03 devnull .PP
 77 058b0118 2005-01-03 devnull The error string is maintained in parallel with the Unix
 78 058b0118 2005-01-03 devnull error number
 79 058b0118 2005-01-03 devnull .IR errno .
 80 058b0118 2005-01-03 devnull Changing
 81 058b0118 2005-01-03 devnull .I errno
 82 058b0118 2005-01-03 devnull will reset the error string,
 83 058b0118 2005-01-03 devnull and changing the error string via
 84 058b0118 2005-01-03 devnull .I errstr
 85 058b0118 2005-01-03 devnull or
 86 058b0118 2005-01-03 devnull .I werrstr
 87 058b0118 2005-01-03 devnull will reset
 88 058b0118 2005-01-03 devnull .IR errno .
 89 cfa37a7b 2004-04-10 devnull .SH SOURCE
 90 c3674de4 2005-01-11 devnull .B \*9/src/lib9/errstr.c
 91 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
 92 cfa37a7b 2004-04-10 devnull .I Errstr
 93 cfa37a7b 2004-04-10 devnull always returns 0.
 94 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
 95 d32deab1 2020-08-16 rsc .MR intro (3) ,
 96 d32deab1 2020-08-16 rsc .MR perror (3)
 97 058b0118 2005-01-03 devnull .SH BUGS
 98 058b0118 2005-01-03 devnull The implementation sets
 99 058b0118 2005-01-03 devnull .I errno
100 058b0118 2005-01-03 devnull to the (somewhat arbitrary) 
101 058b0118 2005-01-03 devnull constant 0x19283745 when
102 058b0118 2005-01-03 devnull the error string is valid.
103 058b0118 2005-01-03 devnull When
104 058b0118 2005-01-03 devnull .I errno
105 058b0118 2005-01-03 devnull is set to other values, the error string
106 058b0118 2005-01-03 devnull is synthesized using
107 d32deab1 2020-08-16 rsc .MR strerror (3) .