Provided by: explain_0.52.D002-1_amd64
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: debug Additional debugging messages for libexplain developers. Not generally useful to clients of the library. Default: false. extra‐device‐info 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 eror message texts. If false, it uses strerorP(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.
Supported System Calls
Each supported system call has its own man page. explain_accept(3) Explain accept(2) errors explain_accept_or_die(3) accept a connection on a socket and report errors explain_accept4(3) Explain accept4(2) errors explain_accept4_or_die(3) accept a connection on a socket and report errors explain_access(3) Explain access(2) errors explain_access_or_die(3) check permissions for a file and report errors explain_acct(3) Explain acct(2) errors explain_acct_or_die(3) process accounting control and report errors explain_adjtime(3) Explain adjtime(2) errors explain_adjtime_or_die(3) smoothly tune kernel clock and report errors explain_adjtimex(3) Explain adjtimex(2) errors explain_adjtimex_or_die(3) tune kernel clock and report errors explain_bind(3) Explain bind(2) errors explain_bind_or_die(3) bind a name to a socket and report errors explain_calloc(3) Explain calloc(3) errors explain_calloc_or_die(3) Allocate and clear memory and report errors explain_chdir(3) Explain chdir(2) errors explain_chdir_or_die(3) change working directory and report errors explain_chmod(3) Explain chmod(2) errors explain_chmod_or_die(3) change permissions of a file and report errors explain_chown(3) Explain chown errors explain_chown_or_die(3) change ownership of a file and report errors explain_chroot(3) Explain chroot(2) errors explain_chroot_or_die(3) change root directory and report errors explain_close(3) Explain close(2) errors explain_close_or_die(3) close a file descriptor and report errors explain_closedir(3) Explain closedir(3) errors explain_closedir_or_die(3) close a directory and report errors explain_connect(3) Explain connect(2) errors explain_connect_or_die(3) initiate a connection on a socket and report errors explain_creat(3) Explain creat(2) errors explain_creat_or_die(3) create and open a file and report errors explain_dirfd(3) Explain dirfd(3) errors explain_dirfd_or_die(3) get directory stream file descriptor and report errors explain_dup(3) Explain dup(2) errors explain_dup_or_die(3) duplicate a file descriptor and report errors explain_dup2(3) Explain dup2(2) errors explain_dup2_or_die(3) duplicate a file descriptor and report errors explain_eventfd(3) Explain eventfd(2) errors explain_eventfd_or_die(3) create a file descriptor for event notification and report errors explain_execlp(3) Explain execlp(3) errors explain_execlp_or_die(3) execute a file and report errors explain_execve(3) Explain execve(2) errors explain_execve_or_die(3) execute program and report errors explain_execvp(3) Explain execvp(3) errors explain_execvp_or_die(3) execute program and report errors explain_exit(3) print an explanation of exit status before exiting explain_fchdir(3) Explain fchdir(2) errors explain_fchmod(3) Explain fchmod(2) errors explain_fchmod_or_die(3) change permissions of a file and report errors explain_fchown(3) Explain fchown(2) errors explain_fchown_or_die(3) change ownership of a file and report errors explain_fclose(3) Explain fclose(2) errors explain_fclose_or_die(3) close a stream and report errors explain_fcntl(3) Explain fcntl(2) errors explain_fcntl_or_die(3) Manipulate a file descriptor and report errors explain_fdopen(3) Explain fdopen(3) errors explain_fdopen_or_die(3) stream open function and report errors explain_fdopendir(3) Explain fdopendir(3) errors explain_fdopendir_or_die(3) open a directory and report errors explain_feof(3) Explain feof(3) errors explain_feof_or_die(3) check and reset stream status and report errors explain_ferror(3) Explain ferror(3) errors explain_ferror_or_die(3) check stream status and report errors explain_fflush(3) Explain fflush(3) errors explain_fflush_or_die(3) flush a stream and report errors explain_fgetc(3) Explain fgetc(3) errors explain_fgetc_or_die(3) input of characters and report errors explain_fgetpos(3) Explain fgetpos(3) errors explain_fgetpos_or_die(3) reposition a stream and report errors explain_fgets(3) Explain fgets(3) errors explain_fgets_or_die(3) input of strings and report errors explain_fileno(3) Explain fileno(3) errors explain_fileno_or_die(3) check and reset stream status and report errors explain_flock(3) Explain flock(2) errors explain_flock_or_die(3) apply or remove an advisory lock on an open file and report errors explain_fopen(3) Explain fopen(3) errors explain_fopen_or_die(2) open files and report errors explain_fork(3) Explain fork(2) errors explain_fork_or_die(3) create a child process and report errors explain_fpathconf(3) Explain fpathconf(3) errors explain_fpathconf_or_die(3) get configuration values for files and report errors explain_fprintf(3) Explain fprintf(3) errors explain_fprintf_or_die(3) formatted output conversion and report errors explain_fpurge(3) Explain fpurge(3) errors explain_fpurge_or_die(3) purge a stream and report errors explain_fputc(3) Explain fputc(3) errors explain_fputc_or_die(3) output of characters and report errors explain_fputs(3) Explain fputs(3) errors explain_fputs_or_die(3) write a string to a stream and report errors explain_fread(3) Explain fread(3) errors explain_fread_or_die(3) binary stream input and report errors explain_freopen(3) Explain freopen(3) errors explain_freopen_or_die(3) open files and report errors explain_fseek(3) Explain fseek(3) errors explain_fseek_or_die(3) reposition a stream and report errors explain_fsetpos(3) Explain fsetpos(3) errors explain_fsetpos_or_die(3) reposition a stream and report errors explain_fstat(3) Explain fstat(3) errors explain_fstat_or_die(3) get file status and report errors explain_fstatfs(3) Explain fstatfs(2) errors explain_fstatfs_or_die(3) get file system statistics and report errors explain_fstatvfs(3) Explain fstatvfs(2) errors explain_fstatvfs_or_die(3) get file system statistics and report errors explain_fsync(3) Explain fsync(2) errors explain_fsync_or_die(3) synchronize a file's in‐core state with storage device and report errors explain_ftell(3) Explain ftell(3) errors explain_ftell_or_die(3) get stream position and report errors explain_ftime(3) Explain ftime(3) errors explain_ftime_or_die(3) return date and time and report errors explain_ftruncate(3) Explain ftruncate(2) errors explain_ftruncate_or_die(3) truncate a file to a specified length and report errors explain_futimes(3) Explain futimes(3) errors explain_futimes_or_die(3) Execute futimes(3) and report errors explain_fwrite(3) Explain fwrite(3) errors explain_fwrite_or_die(3) binary stream output and report errors explain_getaddrinfo(3) Explain getaddrinfo(3) errors explain_getaddrinfo_or_die(3) network address and and report errors explain_getc(3) Explain getc(3) errors explain_getc_or_die(3) input of characters and report errors explain_getchar(3) Explain getchar(3) errors explain_getchar_or_die(3) input of characters and report errors explain_getcwd(3) Explain getcwd(2) errors explain_getdomainname(3) Explain getdomainname(2) errors explain_getdomainname_or_die(3) get domain name and report errors explain_getgroups(3) Explain getgroups(2) errors explain_getgroups_or_die(3) get list of supplementary group IDs and report errors explain_getcwd_or_die(3) Get current working directory and report errors explain_gethostname(3) Explain gethostname(2) errors explain_gethostname_or_die(3) get hostname and report errors explain_getpeername(3) Explain getpeername(2) errors explain_getpeername_or_die(3) Executegetpeername(2) and report errors explain_getpgid(3) Explain getpgid(2) errors explain_getpgid_or_die(3) get process group and report errors explain_getpgrp(3) Explain getpgrp(2) errors explain_getpgrp_or_die(3) get process group and report errors explain_getrlimit(3) Explain getrlimit(2) errors explain_getrlimit_or_die(3) get resource limits and report errors explain_getsockname(3) Explain getsockname(2) errors explain_getsockname_or_die(3) Execute getsockname(2) and report errors explain_getsockopt(3) Explain getsockopt(2) errors explain_getsockopt_or_die(3) Execute getsockopt(2) and report errors explain_gettimeofday(3) Explain gettimeofday(2) errors explain_gettimeofday_or_die(3) get time and report errors explain_getw(3) Explain getw(3) errors explain_getw_or_die(3) input a word (int) and report errors explain_ioctl(3) Explain ioctl(2) errors explain_ioctl_or_die(3) Execute ioctl(2) and report errors explain_kill(3) Explain kill(2) errors explain_kill_or_die(3) send signal to a process and report errors explain_lchown(3) Explain lchown(2) errors explain_lchown_or_die(3) change ownership of a file and report errors explain_link(3) Explain link(2) errors explain_link_or_die(3) make a new name for a file and report errors explain_listen(3) Explain listen(2) errors explain_listen_or_die(3) listen for connections on a socket and report errors explain_lseek(3) Explain lseek(2) errors explain_lseek_or_die(3) reposition file offset and report errors explain_lstat(3) Explain lstat(2) errors explain_lstat_or_die(3) get file status and report errors explain_malloc(3) Explain malloc(3) errors explain_malloc_or_die(3) Execute malloc(3) and report errors explain_mkdir(3) Explain mkdir(2) errors explain_mkdir_or_die(3) create directory and report errors explain_mkdtemp(3) Explain mkdtemp(3) errors explain_mkdtemp_or_die(3) create a unique temporary directory and report errors explain_mknod(3) Explain mknod(2) errors explain_mknod_or_die(3) create a special or ordinary file and report errors explain_mkostemp(3) Explain mkostemp(3) errors explain_mkostemp_or_die(3) create a unique temporary file and report errors explain_mkstemp(3) Explain mkstemp(3) errors explain_mkstemp_or_die(3) create a unique temporary file and report errors explain_mktemp(3) Explain mktemp(3) errors explain_mktemp_or_die(3) make a unique temporary filename and report errors explain_mmap(3) Explain mmap(2) errors explain_mmap_or_die(3) map file or device into memory and report errors explain_munmap(3) Explain munmap(2) errors explain_munmap_or_die(3) unmap a file or device from memory and report errors explain_nice(3) Explain nice(2) errors explain_nice_or_die(3) change process priority and report errors explain_open(3) Explain open(2) errors explain_open_or_die(3) open files and report errors explain_opendir(3) Explain opendir(3) errors explain_opendir_or_die(3) open a directory and report errors explain_pathconf(3) Explain pathconf(3) errors explain_pathconf_or_die(3) get configuration values for files and report errors explain_pclose(3) Explain pclose(3) errors explain_pclose_or_die(3) Execute pclose(3) and report errors explain_pipe(3) Explain pipe(2) errors explain_pipe_or_die(3) Execute pipe(2) and report errors explain_poll(3) Explain poll(2) errors explain_poll_or_die(3) wait for some event on a file descriptor and report errors explain_popen(3) Explain popen(3) errors explain_popen_or_die(3) Execute popen(3) and report errors explain_pread(3) Explain pread(2) errors explain_pread_or_die(3) read from a file descriptor at a given offset and report errors explain_printf(3) Explain printf(3) errors explain_printf_or_die(3) formatted output conversion and report errors explain_ptrace(3) Explain ptrace(2) errors explain_ptrace_or_die(3) process trace and report errors explain_putc(3) Explain putc(3) errors explain_putc_or_die(3) output of characters and report errors explain_putchar(3) Explain putchar(3) errors explain_putchar_or_die(3) output of characters and report errors explain_putenv(3) Explain putenv(3) errors explain_putenv_or_die(3) change or add an environment variable and report errors explain_puts(3) Explain puts(3) errors explain_puts_or_die(3) write a string and a trailing newline to stdout and report errors explain_putw(3) Explain putw(3) errors explain_putw_or_die(3) output a word (int) and report errors explain_pwrite(3) Explain pwrite(2) errors explain_pwrite_or_die(3) write to a file descriptor at a given offset and report errors explain_raise(3) Explain raise(3) errors explain_raise_or_die(3) send a signal to the caller and report errors explain_read(3) Explain read(2) errors explain_read_or_die(3) read from a file descriptor and report errors explain_readdir(3) Explain readdir(3) errors explain_readdir_or_die(3) read a directory and report errors explain_readlink(3) Explain readlink(2) errors explain_readlink_or_die(3) read value of a symbolic link and report errors explain_readv(3) Explain readv(2) errors explain_readv_or_die(3) read data into multiple buffers and report errors explain_realloc(3) Explain realloc(3) errors explain_realloc_or_die(3) Execute realloc(3) and report errors explain_realpath(3) Explain realpath(3) errors explain_realpath_or_die(3) return the canonicalized absolute pathname and report errors explain_rename(3) Explain rename(2) errors explain_rename_or_die(3) change the name or location of a file and report errors explain_rmdir(3) Explain rmdir(2) errors explain_rmdir_or_die(3) delete a directory and report errors explain_select(3) Explain select(2) errors explain_select_or_die(3) execute select(2) and report errors explain_setbuf(3) Explain setbuf(3) errors explain_setbuffer(3) Explain setbuffer(3) errors explain_setbuffer_or_die(3) stream buffering operations and report errors explain_setbuf_or_die(3) set stream buffer and report errors explain_setdomainname(3) Explain setdomainname(2) errors explain_setdomainname_or_die(3) set domain name and report errors explain_setenv(3) Explain setenv(3) errors explain_setenv_or_die(3) change or add an environment variable and report errors explain_setgroups(3) Explain setgroups(2) errors explain_setgroups_or_die(3) get list of supplementary group IDs and report errors explain_sethostname(3) Explain sethostname(2) errors explain_sethostname_or_die(3) set hostname and report errors explain_setlinebuf(3) Explain setlinebuf(3) errors explain_setlinebuf_or_die(3) stream buffering operations and report errors explain_setpgid(3) Explain setpgid(2) errors explain_setpgid_or_die(3) set process group and report errors explain_setpgrp(3) Explain setpgrp(2) errors explain_setpgrp_or_die(3) set process group and report errors explain_setsid(3) Explain setsid(2) errors explain_setsid_or_die(3) creates a session and sets the process group ID and report errors explain_setsockopt(3) Explain setsockopt(2) errors explain_setsockopt_or_die(3) execute setsockopt(2) and report errors explain_setvbuf(3) Explain setvbuf(3) errors explain_setvbuf_or_die(3) stream buffering operations and report errors explain_shmat(3) Explain shmat(2) errors explain_shmat_or_die(3) shared memory attach and report errors explain_shmctl(3) Explain shmctl(2) errors explain_shmctl_or_die(3) shared memory control and report errors explain_signalfd(3) Explain signalfd(2) errors explain_signalfd_or_die(3) create a file descriptor for accepting signals and report errors explain_socket(3) Explain socket(2) errors explain_socket_or_die(3) create an endpoint for communication and report errors explain_socketpair(3) Explain socketpair(2) errors explain_socketpair_or_die(3) create a pair of connected sockets and report errors explain_sprintf(3) Explain sprintf(3) errors explain_sprintf_or_die(3) formatted output conversion and report errors explain_stat(3) Explain stat(2) errors explain_statfs(3) Explain statfs(2) errors explain_statfs_or_die(3) get file system statistics and report errors explain_statvfs(3) Explain statvfs(2) errors explain_statvfs_or_die(3) get file system statistics and report errors explain_stime(3) Explain stime(2) errors explain_stime_or_die(3) set system time and report errors explain_strdup(3) Explain strdup(3) errors explain_strdup_or_die(3) duplicate a string and report errors explain_strndup(3) Explain strndup(3) errors explain_strndup_or_die(3) duplicate a string and report errors explain_strtod(3) Explain strtod(3) errors explain_strtod_or_die(3) convert string to floating‐point number and report errors explain_strtof(3) Explain strtof(3) errors explain_strtof_or_die(3) convert string to floating‐point number and report errors explain_strtol(3) Explain strtol(3) errors explain_strtol_or_die(3) convert a string to a long integer and report errors explain_strtold(3) Explain strtold(3) errors explain_strtold_or_die(3) convert string to floating‐point number and report errors explain_strtoll(3) Explain strtoll(3) errors explain_strtoll_or_die(3) convert a string to a long long integer and report errors explain_strtoul(3) Explain strtoul(3) errors explain_strtoul_or_die(3) convert a string to a long long integer and report errors explain_strtoull(3) Explain strtoull(3) errors explain_strtoull_or_die(3) convert a string to an unsigned long long integer and report errors explain_symlink(3) Explain symlink(2) errors explain_symlink_or_die(3) make a new name for a file and report errors explain_system(3) Explain system(3) errors explain_system_or_die(3) execute a shell command and report errors explain_tcdrain(3) Explain tcdrain(3) errors explain_tcdrain_or_die(3) Execute tcdrain(3) and report errors explain_tcflow(3) Explain tcflow(3) errors explain_tcflow_or_die(3) Execute tcflow(3) and report errors explain_tcflush(3) Explain tcflush(3) errors explain_tcflush_or_die(3) discard terminal data and report errors explain_tcgetattr(3) Explain tcgetattr(3) errors explain_tcgetattr_or_die(3) get terminal parameters and report errors explain_tcsendbreak(3) Explain tcsendbreak(3) errors explain_tcsendbreak_or_die(3) send terminal line break and report errors explain_tcsetattr(3) Explain tcsetattr(3) errors explain_tcsetattr_or_die(3) set terminal attributes and report errors explain_telldir(3) Explain telldir(3) errors explain_telldir_or_die(3) return current location in directory stream and report errors explain_tempnam(3) Explain tempnam(3) errors explain_tempnam_or_die(3) create a name for a temporary file and report errors explain_time(3) Explain time(2) errors explain_time_or_die(3) get time in seconds and report errors explain_timerfd_create(3) Explain timerfd_create(2) errors explain_timerfd_create_or_die(3) timers that notify via file descriptors and report errors explain_tmpfile(3) Explain tmpfile(3) errors explain_tmpfile_or_die(3) create a temporary file and report errors explain_tmpnam(3) Explain tmpnam(3) errors explain_tmpnam_or_die(3) create a name for a temporary file and report errors explain_truncate(3) Explain truncate(2) errors explain_truncate_or_die(3) truncate a file to a specified length and report errors explain_ungetc(3) Explain ungetc(3) errors explain_ungetc_or_die(3) push a character back to a stream and report errors explain_unlink(3) Explain unlink(2) errors explain_unlink_or_die(3) delete a file and report errors explain_unsetenv(3) Explain unsetenv(3) errors explain_unsetenv_or_die(3) remove an environment variable and report errors explain_ustat(3) Explain ustat(2) errors explain_ustat_or_die(3) get file system statistics and report errors explain_utime(3) Explain utime(2) errors explain_utime_or_die(3) change file last access and modification times and report errors explain_utimes(3) Explain utimes(2) errors explain_utimes_or_die(3) change file last access and modification times and report errors explain_vfork(3) Explain vfork(2) errors explain_vfork_or_die(3) create a child process and block parent and report errors explain_vfprintf(3) Explain vfprintf(3) errors explain_vfprintf_or_die(3) formatted output conversion and report errors explain_vprintf(3) Explain vprintf(3) errors explain_vprintf_or_die(3) formatted output conversion and report errors explain_vsnprintf(3) Explain vsnprintf(3) errors explain_vsnprintf_or_die(3) formatted output conversion and report errors explain_snprintf(3) Explain snprintf(3) errors explain_snprintf_or_die(3) formatted output conversion and report errors explain_vsprintf(3) Explain vsprintf(3) errors explain_vsprintf_or_die(3) formatted output conversion and report errors explain_wait(3) Explain wait(2) errors explain_wait_or_die(3) wait for process to change state and report errors explain_wait3(3) Explain wait3(2) errors explain_wait3_or_die(3) wait for process to change state and report errors explain_wait4(3) Explain wait4(2) errors explain_wait4_or_die(3) wait for process to change state and report errors explain_waitpid(3) Explain waitpid(2) errors explain_waitpid_or_die(3) wait for process to change state and report errors explain_write(3) Explain write(2) errors explain_write_or_die(3) write to a file descriptor and report errors explain_writev(3) Explain writev(2) errors explain_writev_or_die(3) 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
errno(3) number of last error perror(3) print a system error message strerror(3) return string describing error number
COPYRIGHT
libexplain version 0.52 Copyright (C) 2008 Peter Miller
AUTHOR
Written by Peter Miller <pmiller@opensource.org.au> libexplain(3)