The libexplain library exists to give explanations of error
reported by system calls. The error message returned by strerror(3)
tend to be quite cryptic. By providing a specific error report for each
system call, a more detailed error message is possible, usually identifying
and describing the specific cause from amongst the numerous meanings each
errno value maps to.
The explanation of the cause of an error is dependent on the
environment of the error to remain unchanged, so that when libexplain gets
around to looking for the cause, the cause is still there. On a running
system, and particularly a multi‐user system, this is not always
possible.
If an incorrect explanation is provided, it is possible that the
cause is no longer present.
Assuming the library header files has been installed into
/usr/include, and the library files have been
installed into /usr/lib, compiling against
libexplain requires no special -I options.
When linking your pograms, add -lexplain
to the list of libraries at the end of your link line.
cc ... -lexplain
When you configure your package with GNU Autoconf, you need the
large file support macro
AC_SYS_LARGEFILE
If you aren't using GNU Autoconf, you will have to work out the
needed large file support requirements yourdelf.
There is a pkg‐config(1) package for you to use,
too:
CFLAGS="$CFLAGS `pkg-config libexplain
--cflags`" LIBS="$LIBS `pkg-config libexplain --libs`"
This can make figuring out the command line requirements much easier.
The EXPLAIN_OPTIONS environment variable
may be used to control some of the content in the messages. Options are
separated by comma (“,”) characters.
There are three ways to set an option:
- 1.
- The form “name=value” may be used explicitly.
The values “true” and “false” are used for
boolean options.
- 2.
- An option name alone is interpreted to mean
“name=true”.
- 3.
- The form “no‐name” is interpreted to mean
“name=false”.
The following options are available:
- debug
- Additional debugging messages for libexplain developers. Not generally
useful to clients of the library.
Default: false.
- Additional information for block and character special devices is printed
when naming a file and its type.
Default: true
- numeric‐errno
- This option includes the numeric errno value in the message,
e.g. “(2, ENOENT)” rather than
“(ENOENT)”. Disabling this option is generally of use in
automated testing, to prevent UNIX dialect differences from producing
false negatives.
Default: true
- dialect‐specific
- This controls the presence of explanatory text specific to a particular
UNIX dialect. It also suppresses printing system specific maximums.
Disabling this option is generally of use in automated testing, to prevent
UNIX dialect differences from producing false negatives.
Default: true.
- hanging‐indent
- This controls the hanging indent depth used for error message wrapping. By
default no hanging indent is used, but this can sometimes obfuscate the
end of one error message and the beginning of another. A hanging indent
results in continuation lines starting with white spoace, similar to
RFC822 headers. A value of 0 means no hanging indent (all lines flush with
left margin). A common value to use is 4: it doesn't consume to much of
each line, and it is a clear indent. The program may choose to override
the environment variable using the
explain_option_hanging_indent_set(3) function. The hanging indent
is limited to 10% of the terminal width.
Default: 0
- internal‐strerror
- This option controls the source of system error message texts. If false,
it uses strerrorP(3) for the text. If true, it uses internal
string for the text. This is mostly of use for automated testing,
to avoid false negatives induced by inconsistencies across Unix
implementations.
Default: false.
- program‐name
- This option controls the inclusion of the program name at the start of
error messages, by the explain_*_or_die and explain_*_on_error functions.
This helps users understand which command is throwing the error. Disabling
this option may be of some interest to script writers. Program developers
can use the explain_program_name_set(3) function to set the name of
the command, if they wish to override the name that libexplain would
otherwise obtain from the operating system. Program developers can use the
explain_program_name_assemble(3) function to trump this option.
Default: true.
- symbolic‐mode‐bits
- This option controls how permission mode bits are represented in error
messages. Setting this option to true will cause symbolic names to be
printed (e.g. S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH). Setting this
option to false will cause octal values to be printed (e.g. 0644).
Default: false.