Scroll to navigation

libexplain(3) Library Functions Manual libexplain(3)

NAME

libexplain - Explain errno values returned by libc functions

SYNOPSIS

cc ... -lexplain;

#include <libexplain/libexplain.h>

DESCRIPTION

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.

Race Condition

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.

Compiling

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.

Environment Variable

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:

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
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
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.
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
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.
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.
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.

Supported System Calls

Each supported system call has its own man page.

Explain accept(2) errors
accept a connection on a socket and report errors
Explain accept4(2) errors
accept a connection on a socket and report errors
Explain access(2) errors
check permissions for a file and report errors
Explain acct(2) errors
process accounting control and report errors
Explain acl_from_text(3) errors
create an ACL from text and report errors
Explain acl_get_fd(3) errors
Execute acl_get_fd(3) and report errors
Explain acl_get_file(3) errors
Execute acl_get_file(3) and report errors
Explain acl_set_fd(3) errors
set an ACL by file descriptor and report errors
Explain acl_set_file(3) errors
set an ACL by filename and report errors
Explain acl_to_text(3) errors
convert an ACL to text and report errors
Explain adjtime(2) errors
smoothly tune kernel clock and report errors
Explain adjtimex(2) errors
tune kernel clock and report errors
Explain asprintf(3) errors
print to allocated string and report errors
Explain bind(2) errors
bind a name to a socket and report errors
Explain calloc(3) errors
Allocate and clear memory and report errors
Explain chdir(2) errors
change working directory and report errors
Explain chmod(2) errors
change permissions of a file and report errors
Explain chown errors
change ownership of a file and report errors
Explain chroot(2) errors
change root directory and report errors
Explain close(2) errors
close a file descriptor and report errors
Explain closedir(3) errors
close a directory and report errors
Explain connect(2) errors
initiate a connection on a socket and report errors
Explain creat(2) errors
create and open a file and report errors
Explain dirfd(3) errors
get directory stream file descriptor and report errors
Explain dup(2) errors
duplicate a file descriptor and report errors
Explain dup2(2) errors
duplicate a file descriptor and report errors
Explain endgrent(3) errors
finish group file accesses and report errors
Explain eventfd(2) errors
create a file descriptor for event notification and report errors
Explain execlp(3) errors
execute a file and report errors
Explain execv(3) errors
execute a file and report errors
Explain execve(2) errors
execute program and report errors
Explain execvp(3) errors
execute program and report errors
print an explanation of exit status before exiting
Explain fchdir(2) errors
Explain fchmod(2) errors
change permissions of an open file and report errors
Explain fchown(2) errors
change ownership of a file and report errors
Explain fchownat(2) errors
change ownership of a file relative to a directory and report errors
Explain fclose(2) errors
close a stream and report errors
Explain fcntl(2) errors
Manipulate a file descriptor and report errors
Explain fdopen(3) errors
stream open function and report errors
Explain fdopendir(3) errors
open a directory and report errors
Explain feof(3) errors
check and reset stream status and report errors
Explain ferror(3) errors
check stream status and report errors
Explain fflush(3) errors
flush a stream and report errors
Explain fgetc(3) errors
input of characters and report errors
Explain fgetpos(3) errors
reposition a stream and report errors
Explain fgets(3) errors
input of strings and report errors
Explain fileno(3) errors
check and reset stream status and report errors
Explain flock(2) errors
apply or remove an advisory lock on an open file and report errors
Explain fopen(3) errors
open files and report errors
Explain fork(2) errors
create a child process and report errors
Explain fpathconf(3) errors
get configuration values for files and report errors
Explain fprintf(3) errors
formatted output conversion and report errors
Explain fpurge(3) errors
purge a stream and report errors
Explain fputc(3) errors
output of characters and report errors
Explain fputs(3) errors
write a string to a stream and report errors
Explain fread(3) errors
binary stream input and report errors
Explain freopen(3) errors
open files and report errors
Explain fseek(3) errors
reposition a stream and report errors
Explain fseeko(3) errors
seek to or report file position and report errors
Explain fsetpos(3) errors
reposition a stream and report errors
Explain fstat(3) errors
get file status and report errors
Explain fstatat(2) errors
get file status relative to a directory file descriptor and report errors
Explain fstatfs(2) errors
get file system statistics and report errors
Explain fstatvfs(2) errors
get file system statistics and report errors
Explain fsync(2) errors
synchronize a file's in‐core state with storage device and report errors
Explain ftell(3) errors
get stream position and report errors
Explain ftello(3) errors
get stream position and report errors
Explain ftime(3) errors
return date and time and report errors
Explain ftruncate(2) errors
truncate a file to a specified length and report errors
Explain futimens(3) errors
change file timestamps with nanosecond precision and report errors
Explain futimes(3) errors
Execute futimes(3) and report errors
Explain futimesat(2) errors
change timestamps of a file relative to a directory and report errors
Explain fwrite(3) errors
binary stream output and report errors
Explain futimesat(2) errors
change timestamps of a file relative to a directory and report errors
Explain getaddrinfo(3) errors
network address and and report errors
Explain getc(3) errors
input of characters and report errors
Explain getchar(3) errors
input of characters and report errors
Explain getcwd(2) errors
Explain getdomainname(2) errors
get domain name and report errors
Explain getgrent(3) errors
get group file entry and report errors
Explain getgrouplist(3) errors
get list of groups to which a user belongs and report errors
Explain getgroups(2) errors
get list of supplementary group IDs and report errors
Get current working directory and report errors
Explain gethostbyname(3) errors
get host address given host name and report errors
Explain gethostid(3) errors
get the unique identifier of the current host and report errors
Explain gethostname(2) errors
get hostname and report errors
Explain getpeername(2) errors
Executegetpeername(2) and report errors
Explain getpgid(2) errors
get process group and report errors
Explain getpgrp(2) errors
get process group and report errors
Explain getpriority(2) errors
get program scheduling priority and report errors
Explain getresgid(2) errors
get real, effective and saved group IDs and report errors
Explain getresuid(2) errors
get real, effective and saved user IDs and report errors
Explain getrlimit(2) errors
get resource limits and report errors
Explain getrusage(2) errors
get resource usage and report errors
Explain getsockname(2) errors
Execute getsockname(2) and report errors
Explain getsockopt(2) errors
Execute getsockopt(2) and report errors
Explain gettimeofday(2) errors
get time and report errors
Explain getw(3) errors
input a word (int) and report errors
Explain iconv(3) errors
perform character set conversion and report errors
Explain iconv_close(3) errors
deallocate descriptor for character set conversion and report errors
Explain iconv_open(3) errors
allocate descriptor for character set conversion and report errors
Explain ioctl(2) errors
Execute ioctl(2) and report errors
Explain kill(2) errors
send signal to a process and report errors
Explain lchmod(2) errors
change permissions of a file and report errors
Explain lchown(2) errors
change ownership of a file and report errors
Explain lchownat(2) errors
Execute lchownat(2) and report errors
Explain link(2) errors
make a new name for a file and report errors
Explain linkat(2) errors
create a file link relative to directory file descriptors and report errors
Explain listen(2) errors
listen for connections on a socket and report errors
Explain lseek(2) errors
reposition file offset and report errors
Explain lstat(2) errors
get file status and report errors
Explain lutimes(3) errors
modify file timestamps and report errors
Explain malloc(3) errors
Execute malloc(3) and report errors
Explain mkdir(2) errors
create directory and report errors
Explain mkdtemp(3) errors
create a unique temporary directory and report errors
Explain mknod(2) errors
create a special or ordinary file and report errors
Explain mkostemp(3) errors
create a unique temporary file and report errors
Explain mkstemp(3) errors
create a unique temporary file and report errors
Explain mktemp(3) errors
make a unique temporary filename and report errors
Explain mmap(2) errors
map file or device into memory and report errors
Explain mount(2) errors
mount file system and report errors
Explain munmap(2) errors
unmap a file or device from memory and report errors
Explain nanosleep(2) errors

high‐resolution sleep and report errors
Explain nice(2) errors
change process priority and report errors
Explain open(2) errors
open files and report errors
Explain openat(2) errors
open a file relative to a directory file descriptor and report errors
Explain opendir(3) errors
open a directory and report errors
Explain pathconf(3) errors
get configuration values for files and report errors
Explain pclose(3) errors
Execute pclose(3) and report errors
Explain pipe(2) errors
Execute pipe(2) and report errors
Explain pipe2(2) errors
create pipe and report errors
Explain poll(2) errors
wait for some event on a file descriptor and report errors
Explain popen(3) errors
Execute popen(3) and report errors
Explain pread(2) errors
read from a file descriptor at a given offset and report errors
Explain printf(3) errors
formatted output conversion and report errors
Explain ptrace(2) errors
process trace and report errors
Explain putc(3) errors
output of characters and report errors
Explain putchar(3) errors
output of characters and report errors
Explain putenv(3) errors
change or add an environment variable and report errors
Explain puts(3) errors
write a string and a trailing newline to stdout and report errors
Explain putw(3) errors
output a word (int) and report errors
Explain pwrite(2) errors
write to a file descriptor at a given offset and report errors
Explain raise(3) errors
send a signal to the caller and report errors
Explain read(2) errors
read from a file descriptor and report errors
Explain readdir(3) errors
read a directory and report errors
Explain readlink(2) errors
read value of a symbolic link and report errors
Explain readv(2) errors
read data into multiple buffers and report errors
Explain realloc(3) errors
Execute realloc(3) and report errors
Explain realpath(3) errors
return the canonicalized absolute pathname and report errors
Explain rename(2) errors
change the name or location of a file and report errors
Explain rmdir(2) errors
delete a directory and report errors
Explain select(2) errors
execute select(2) and report errors
Explain setbuf(3) errors
Explain setbuffer(3) errors
stream buffering operations and report errors
set stream buffer and report errors
Explain setdomainname(2) errors
set domain name and report errors
Explain setenv(3) errors
change or add an environment variable and report errors
Explain setgid(2) errors
set group identity and report errors
Explain setgrent(3) errors
rewind to the start of the group database and report errors
Explain setgroups(2) errors
get list of supplementary group IDs and report errors
Explain sethostname(2) errors
set hostname and report errors
Explain setlinebuf(3) errors
stream buffering operations and report errors
Explain setpgid(2) errors
set process group and report errors
Explain setpgrp(2) errors
set process group and report errors
Explain setpriority(2) errors
set program scheduling priority and report errors
Explain setregid(2) errors
set real and/or effective group ID and report errors
Explain setreuid(2) errors
set the real and effective user ID and report errors
Explain setresgid(2) errors
set real, effective and saved group ID and report errors
Explain setresuid(2) errors
set real, effective and saved user ID and report errors
Explain setreuid(2) errors
set real and/or effective user ID and report errors
Explain setsid(2) errors
creates a session and sets the process group ID and report errors
Explain setsockopt(2) errors
execute setsockopt(2) and report errors
Explain settimeofday(2) errors
sets system time and report errors
Explain setuid(2) errors
set user identity and report errors
Explain setvbuf(3) errors
stream buffering operations and report errors
Explain shmat(2) errors
shared memory attach and report errors
Explain shmctl(2) errors
shared memory control and report errors
Explain signalfd(2) errors
create a file descriptor for accepting signals and report errors
Explain sleep(3) errors
Sleep for the specified number of seconds and report errors
Explain socket(2) errors
create an endpoint for communication and report errors
Explain socketpair(2) errors
create a pair of connected sockets and report errors
Explain sprintf(3) errors
formatted output conversion and report errors
Explain stat(2) errors
Explain statfs(2) errors
get file system statistics and report errors
Explain statvfs(2) errors
get file system statistics and report errors
Explain stime(2) errors
set system time and report errors
Explain strcoll(3) errors
compare two strings using the current locale and report errors
Explain strdup(3) errors
duplicate a string and report errors
Explain strndup(3) errors
duplicate a string and report errors
Explain strtod(3) errors
convert string to floating‐point number and report errors
Explain strtof(3) errors
convert string to floating‐point number and report errors
Explain strtol(3) errors
convert a string to a long integer and report errors
Explain strtold(3) errors
convert string to floating‐point number and report errors
Explain strtoll(3) errors
convert a string to a long long integer and report errors
Explain strtoul(3) errors
convert a string to a long long integer and report errors
Explain strtoull(3) errors
convert a string to an unsigned long long integer and report errors
Explain symlink(2) errors
make a new name for a file and report errors
Explain system(3) errors
execute a shell command and report errors
Explain tcdrain(3) errors
Execute tcdrain(3) and report errors
Explain tcflow(3) errors
Execute tcflow(3) and report errors
Explain tcflush(3) errors
discard terminal data and report errors
Explain tcgetattr(3) errors
get terminal parameters and report errors
Explain tcsendbreak(3) errors
send terminal line break and report errors
Explain tcsetattr(3) errors
set terminal attributes and report errors
Explain telldir(3) errors
return current location in directory stream and report errors
Explain tempnam(3) errors
create a name for a temporary file and report errors
Explain time(2) errors
get time in seconds and report errors
Explain timerfd_create(2) errors
timers that notify via file descriptors and report errors
Explain tmpfile(3) errors
create a temporary file and report errors
Explain tmpnam(3) errors
create a name for a temporary file and report errors
Explain truncate(2) errors
truncate a file to a specified length and report errors
Explain usleep(3) errors
suspend execution for microsecond intervals and report errors
Explain uname(2) errors
get name and information about current kernel and report errors
Explain ungetc(3) errors
push a character back to a stream and report errors
Explain unlink(2) errors
delete a file and report errors
Explain unsetenv(3) errors
remove an environment variable and report errors
Explain ustat(2) errors
get file system statistics and report errors
Explain utime(2) errors
change file last access and modification times and report errors
Explain utimens(2) errors
change file last access and modification times and report errors
Explain utimensat(2) errors
change file timestamps with nanosecond precision and report errors
Explain utimes(2) errors
change file last access and modification times and report errors
Explain vasprintf(3) errors
print to allocated string and report errors
Explain vfork(2) errors
create a child process and block parent and report errors
Explain vfprintf(3) errors
formatted output conversion and report errors
Explain vprintf(3) errors
formatted output conversion and report errors
Explain vsnprintf(3) errors
formatted output conversion and report errors
Explain snprintf(3) errors
formatted output conversion and report errors
Explain vsprintf(3) errors
formatted output conversion and report errors
Explain wait(2) errors
wait for process to change state and report errors
Explain wait3(2) errors
wait for process to change state and report errors
Explain wait4(2) errors
wait for process to change state and report errors
Explain waitpid(2) errors
wait for process to change state and report errors
Explain write(2) errors
write to a file descriptor and report errors
Explain writev(2) errors
write data from multiple buffers and report errors

There are plans for additional coverage. This list is expected to expand in later releases of this library.

SEE ALSO

number of last error
print a system error message
return string describing error number

COPYRIGHT

libexplain version 1.4
Copyright (C) 2008 Peter Miller

AUTHOR

Written by Peter Miller <pmiller@opensource.org.au>