errstr.3 (2101B)
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) .