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 bf8a59fa 2004-04-11 devnull .IR 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 cfa37a7b 2004-04-10 devnull .SH SOURCE
77 b5fdffee 2004-04-19 devnull .B /usr/local/plan9/src/libc/9syscall
78 cfa37a7b 2004-04-10 devnull .br
79 b5fdffee 2004-04-19 devnull .B /usr/local/plan9/src/libc/9sys/werrstr.c
80 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
81 cfa37a7b 2004-04-10 devnull .I Errstr
82 cfa37a7b 2004-04-10 devnull always returns 0.
83 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
84 bf8a59fa 2004-04-11 devnull .IR intro (3),
85 bf8a59fa 2004-04-11 devnull .IR perror (3)