libexplain Documentation

The libexplain library provides a set of functions that may be used to explain Unix and Linux system call errors. This will make your application's error messages much more understandable to your users.

The library is not quite a drop-in replacement for strerror, but it comes close. Each system call has a dedicated libexplain function, for example

 fd = open(path, flags, mode);
 if (fd < 0)
 {
     fprintf(stderr, "%s\n", explain_open(path, flags, mode));
     exit(EXIT_FAILURE);
 }

If, for example, you were to try to open no-such-dir/some-file, the above code would print the following error message:

 open(path = "no-such-dir/some-file", flags = O_RDONLY)
 failed, No such file or directory (2, ENOENT) because there is no
 "no-such-dir" directory in the current directory

The above code comes pre-packaged in the form of the explain_open_or_die function. Using this helper function, the code fragment above may be written as:

 fd = explain_open_or_die(path, flags, mode);

Helper functions are available for all supported system calls. They come in two varieties: explain_name_or_die and explain_name_on_error. The latter prints the error, but still returns to the caller with the original error code.

The library also provides thread safe function variations.

Large File Support

LibExplain Home Page