1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
'\" t
.\"
.\" libexplain - Explain errno values returned by libc functions
.\" Copyright (C) 2008-2011 Peter Miller
.\" Written by Peter Miller <pmiller@opensource.org.au>
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
.\" General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
.\"
.cp 0
.TH "Read Me" libexplain libexplain "Reference Manual"
.so etc/version.so
.hy 0
.ad l
.SH NAME
libexplain \- Explain errno values returned by libc functions
.XX "" "The README file"
.SH DESCRIPTION
The \fIlibexplain\fP package
provides a library which may be used to explain
Unix and Linux system call errors.
This will make your application's error messages much more
informative to your users.
.PP
The library is not quite a drop\[hy]in replacement for
\f[I]strerror\fP(3), but it
comes close.
Each system call has a dedicated libexplain function, for example
.RS
.ft CW
.nf
fd = open(path, flags, mode);
if (fd < 0)
{
fprintf(stderr, "%s\en", explain_open(path, flags, mode));
exit(EXIT_FAILURE);
}
.fi
.ft R
.RE
If, for example, you were to try to open
\f[CW]no\[hy]such\[hy]dir/some\[hy]file\fP, you would see a message like
.RS
\f[CW]open(pathname = "no\[hy]such\[hy]dir/some\[hy]file", flags = O_RDONLY)
failed, No such file or directory (2, ENOENT) because there is no
"no\[hy]such\[hy]dir" directory in the current directory\fP
.RE
.PP
The good new is that for each of these functions there is a wrapper
function, in this case \f[I]explain_open_or_die\fP(3), that includes
the above code fragment. Adding good error reporting is as simple as
using a different, but similarly named, function.
The library also provides thread safe variants of each explanation function.
.PP
.so etc/coverage.so
.SS Tutorial Documentation
There is a paper available in PDF format
(http://libexplain.sourceforge.net/\%lca2010/\%lca2010.pdf)
that describes the library and
how to use LibExplain.
The paper can also be accessed as \f[I]explain_lca2010\fP(1),
which also appears in the reference manual (see below).
.br
.ne 1i
.SH HOME PAGE
The latest version of
.I libexplain
is available on the Web from:
.TS
center,tab(;);
l l s
l l l.
URL:;http://libexplain.sourceforge.net/
File:;index.html;# the libexplain page
File:;libexplain.\*(v).README;# Description, from the tar file
File:;libexplain.\*(v).lsm;# Description, LSM format
File:;libexplain.\*(v).tar.gz;# the complete source
File:;libexplain.\*(v).pdf;# Reference Manual
.TE
.br
.ne 1i
.SH BUILDING LIBEXPLAIN
Full instructions for building
.I libexplain
may be found in the
.I BUILDING
file included in this distribution.
.br
.ne 1i
.SH COPYRIGHT
.I libexplain
version \*(v)
.br
Copyright
.if t \(co
.if n (C)
\*(Y) Peter Miller
.SS Library License
\f[I]The shared library, and its include files, are GNU LGPL licensed.\fP
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 3 of the License, or (at
your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.
.PP
You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
.SS Non-Library License
\f[I]Everything else (all source files that do not constitute the shared
library and its include files) are GNU GPL licensed.\fP
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 3 of the License, or (at your
option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
.PP
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
.br
.ne 1i
.SH AUTHOR
.TS
tab(;);
l r l.
Peter Miller;E\[hy]Mail:;pmiller@opensource.org.au
\f(CW/\e/\e*\fP;WWW:;http://www.canb.auug.org.au/~millerp/
.TE
.br
.bp
.SH RELEASE NOTES
.XX "" "Release Notes"
This section details the various features and bug fixes of the various
releases. For excruciating and complete detail, and also credits for
those of you who have generously sent me suggestions and bug reports,
see the \fIetc/CHANGES.*\fP files.
.PP
.so etc/coverage.so
.so etc/new.so
|
