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