.hy 0
.ad l
.nf
No Medium Found, 3.0, Notes
3. Message Content
This code:
int fd = explain_open_or_die("some/thing", O_RDONLY, 0);
produces this messsage:
open(pathname = "some/file", flags = O_RDONLY) failed,
No such file or directory (2, ENOENT) because there is
no "some" directory in the current directory
This breaks down into three pieces:
system-call failed, system-error because explanation
 3.1 Before Because 
slide
open(pathname = "some/file", flags = O_RDONLY) failed,
No such file or directory (2, ENOENT) because ...
-  This is the proximal cause.
-  Developers find it useful.
-  If not in error message, user can't copy-and-paste into bug report.
-  Maintainers find that useful (once apon a time, on a file system
     far, far away...)
-  Arguments names used in explanation for context.
-  Note: I have been using error messages with this level of detail
     for many years, and they go over rather well, contrary to expectations.
-  Users like it when you don't talk down to them.
     Give them some credit.
 3.2 After Because 
slide
\&...because there is no "some" directory in the current directory
-  This portion attempts to explain the proximal cause of the error in
plain language.
-  It attempts to include as much information as possible,
- possibly delving deeply into the semantics of the system call,
- including looking at owners and permission bits.
 3.3 Internationalization 
slide
-  Most of them — left over proof-of-concept
-  No localizations
 3.4 Postmortem 
slide
-  explain
-  need to know system call
-  need to know errno
-  how to turn errno value into string
 explain -e num strerror
 3.5 Philosophy 
slide
-  Tell me everything.
-  Including what I didn't know to look for (or how to look for)
-  Avoid modifying process (thread) state
-  Absolute paths if relative paths would be ambiguous