xenial (1) explain_lca2010.1.gz

Provided by: explain_1.4.D001-2_amd64 bug

NAME

       explain_lca2010 - No medium found: when it's time to stop trying to read strerror(3)'s mind.

MOTIVATION

       The idea for libexplain occurred to me back in the early 1980s.  Whenever a system call returns an error,
       the kernel knows exactly what went wrong... and compresses this into less that 8  bits  of  errno.   User
       space  has  access  to  the  same  data as the kernel, it should be possible for user space to figure out
       exactly what happened to provoke the error return, and use this to write good error messages.

       Could it be that simple?

   Error messages as finesse
       Good error messages are often those “one percent” tasks that get dropped when schedule pressure  squeezes
       your  project.   However,  a good error message can make a huge, disproportionate improvement to the user
       experience, when the user wanders into scarey unknown territory not usually encountered.  This is no easy
       task.

       As  a larval programmer, the author didn't see the problem with (completely accurate) error messages like
       this one:
              floating exception (core dumped)
       until the alternative non‐programmer interpretation was pointed out.  But that isn't the only thing wrong
       with Unix error messages.  How often do you see error messages like:
              $ ./stupid
              can't open file
              $
       There are two options for a developer at this point:

       1.
         you can run a debugger, such as gdb(1), or

       2.
         you can use strace(1) or truss(1) to look inside.

       • Remember  that  your  users may not even have access to these tools, let alone the ability to use them.
         (It's a very long time since Unix beginner meant “has only written one device driver”.)

       In this example, however, using strace(1) reveals
              $ strace -e trace=open ./stupid
              open("some/file", O_RDONLY) = -1 ENOENT (No such file or directory)
              can't open file
              $
       This is considerably more information than the error message provides.  Typically, the stupid source code
       looks like this
              int fd = open("some/thing", O_RDONLY);
              if (fd < 0)
              {
                  fprintf(stderr, "can't open file\n");
                  exit(1);
              }
       The  user  isn't  told which file, and also fails to tell the user which error.  Was the file even there?
       Was there a permissions problem?  It does tell you it was trying to open a file, but that was probably by
       accident.

       Grab your clue stick and go beat the larval programmer with it.  Tell him about perror(3).  The next time
       you use the program you see a different error message:
              $ ./stupid
              open: No such file or directory
              $
       Progress, but not what we expected.  How can the user fix the problem if the error message  doesn't  tell
       him what the problem was?  Looking at the source, we see
              int fd = open("some/thing", O_RDONLY);
              if (fd < 0)
              {
                  perror("open");
                  exit(1);
              }
       Time  for  another  run with the clue stick.  This time, the error message takes one step forward and one
       step back:
              $ ./stupid
              some/thing: No such file or directory
              $
       Now we know the file it was trying to open, but are no longer informed that it was open(2)  that  failed.
       In  this case it is probably not significant, but it can be significant for other system calls.  It could
       have been creat(2) instead, an operation implying that different permissions are necessary.
              const char *filename = "some/thing";
              int fd = open(filename, O_RDONLY);
              if (fd < 0)
              {
                  perror(filename);
                  exit(1);
              }
       The above example code is unfortunately typical of non‐larval programmers as  well.   Time  to  tell  our
       padawan learner about the strerror(3) system call.
              $ ./stupid
              open some/thing: No such file or directory
              $
       This maximizes the information that can be presented to the user.  The code looks like this:
              const char *filename = "some/thing";
              int fd = open(filename, O_RDONLY);
              if (fd < 0)
              {
                  fprintf(stderr, "open %s: %s\n", filename, strerror(errno));
                  exit(1);
              }
       Now  we have the system call, the filename, and the error string.  This contains all the information that
       strace(1) printed.  That's as good as it gets.

       Or is it?

   Limitations of perror and strerror
       The problem the author saw, back in the 1980s, was that the error message is incomplete.  Does  “no  such
       file or directory” refer to the “some” directory, or to the “thing” file in the “some” directory?

       A quick look at the man page for strerror(3) is telling:
              strerror - return string describing error number
       Note well: it is describing the error number, not the error.

       On  the  other hand, the kernel knows what the error was.  There was a specific point in the kernel code,
       caused by a specific condition, where the kernel code branched and said “no”.  Could a user‐space program
       figure out the specific condition and write a better error message?

       However, the problem goes deeper.  What if the problem occurs during the read(2) system call, rather than
       the open(2) call?  It is simple for the error message associated with open(2) to include the  file  name,
       it's  right there.  But to be able to include a file name in the error associated with the read(2) system
       call, you have to pass the file name all the way down the call stack, as well as the file descriptor.

       And here is the bit that grates: the  kernel  already  knows  what  file  name  the  file  descriptor  is
       associated  with.   Why  should  a programmer have to pass redundant data all the way down the call stack
       just to improve an error message that may never be issued?  In reality, many  programmers  don't  bother,
       and the resulting error messages are the worse for it.

       But that was the 1980s, on a PDP11, with limited resources and no shared libraries.  Back then, no flavor
       of Unix included /proc even in rudimentary form, and the lsof(1) program was over a decade away.  So  the
       idea was shelved as impractical.

   Level Infinity Support
       Imagine  that you are level infinity support.  Your job description says that you never ever have to talk
       to users.  Why, then, is there still a constant stream of people wanting you, the  local  Unix  guru,  to
       decipher yet another error message?

       Strangely,  25  years  later, despite a simple permissions system, implemented with complete consistency,
       most Unix users still have no idea how to decode “No such file or directory”, or any of the other cryptic
       error messages they see every day.  Or, at least, cryptic to them.

       Wouldn't  it  be  nice if first level tech support didn't need error messages deciphered?  Wouldn't it be
       nice to have error messages that users could understand without calling tech support?

       These days /proc on Linux is more than able to provide the  information  necessary  to  decode  the  vast
       majority  of error messages, and point the user to the proximate cause of their problem.  On systems with
       a limited /proc implementation, the lsof(1) command can fill in many of the gaps.

       In 2008, the stream of translation requests happened to the author way too often.  It  was  time  to  re‐
       examine that 25 year old idea, and libexplain is the result.

USING THE LIBRARY

       The  interface  to the library tries to be consistent, where possible.  Let's start with an example using
       strerror(3):
              if (rename(old_path, new_path) < 0)
              {
                  fprintf(stderr, "rename %s %s: %s\n", old_path, new_path,
                      strerror(errno));
                  exit(1);
              }
       The idea behind libexplain is to  provide  a  strerror(3)  equivalent  for  each  system  call,  tailored
       specifically  to  that system call, so that it can provide a more detailed error message, containing much
       of the information you see under the “ERRORS” heading of section 2 and 3  man  pages,  supplemented  with
       information about actual conditions, actual argument values, and system limits.

   The Simple Case
       The strerror(3) replacement:
              if (rename(old_path, new_path) < 0)
              {
                  fprintf(stderr, "%s\n", explain_rename(old_path, new_path));
                  exit(1);
              }

   The Errno Case
       It  is  also possible to pass an explicit errno(3) value, if you must first do some processing that would
       disturb errno, such as error recovery:
              if (rename(old_path, new_path < 0))
              {
                  int old_errno = errno;
                  ...code that disturbs errno...
                  fprintf(stderr, "%s\n", explain_errno_rename(old_errno,
                      old_path, new_path));
                  exit(1);
              }

   The Multi‐thread Cases
       Some applications are multi‐threaded, and thus are unable to share libexplain's internal buffer.  You can
       supply your own buffer using
              if (unlink(pathname))
              {
                  char message[3000];
                  explain_message_unlink(message, sizeof(message), pathname);
                  error_dialog(message);
                  return -1;
              }
       And for completeness, both errno(3) and thread‐safe:
              ssize_t nbytes = read(fd, data, sizeof(data));
              if (nbytes < 0)
              {
                  char message[3000];
                  int old_errno = errno;
                  ...error recovery...
                  explain_message_errno_read(message, sizeof(message),
                      old_errno, fd, data, sizeof(data));
                  error_dialog(message);
                  return -1;
              }

       These are replacements for strerror_r(3), on systems that have it.

   Interface Sugar
       A set of functions added as convenience functions, to woo programmers to use the libexplain library, turn
       out to be the author's most commonly used libexplain functions in command line programs:
              int fd = explain_creat_or_die(filename, 0666);
       This function attempts to create a new file.  If it can't, it prints an  error  message  and  exits  with
       EXIT_FAILURE.  If there is no error, it returns the new file descriptor.

       A related function:
              int fd = explain_creat_on_error(filename, 0666);
       will  print  the  error  message  on failure, but also returns the original error result, and errno(3) is
       unmolested, as well.

   All the other system calls
       In general, every system call has its own include file
              #include <libexplain/name.h>
       that defines function prototypes for six functions:

       • explain_name,

       • explain_errno_name,

       • explain_message_name,

       • explain_message_errno_name,

       • explain_name_or_die and

       • explain_name_on_error.

       Every function prototype has Doxygen documentation, and this  documentation  is  not  stripped  when  the
       include files are installed.

       The  wait(2) system call (and friends) have some extra variants that also interpret failure to be an exit
       status that isn't EXIT_SUCCESS.  This applies to system(3) and pclose(3) as well.

       Coverage includes 221 system calls and 547 ioctl requests.  There are  many  more  system  calls  yet  to
       implement.   System  calls  that  never return, such as exit(2), are not present in the library, and will
       never be.  The exec family of system calls are supported, because they return when there is an error.

   Cat
       This is what a hypothetical “cat” program could look like, with full error reporting, using libexplain.
              #include <libexplain/libexplain.h>
              #include <stdlib.h>
              #include <unistd.h>
       There is one include for libexplain, plus the usual suspects.  (If you wish to  reduce  the  preprocessor
       load, you can use the specific <libexplain/name.h> includes.)
              static void
              process(FILE *fp)
              {
                  for (;;)
                  {
                      char buffer[4096];
                      size_t n = explain_fread_or_die(buffer, 1, sizeof(buffer), fp);
                      if (!n)
                          break;
                      explain_fwrite_or_die(buffer, 1, n, stdout);
                  }
              }
       The  process  function  copies  a  file  stream to the standard output.  Should an error occur for either
       reading or writing, it is reported (and the pathname will be included in the error) and the command exits
       with  EXIT_FAILURE.   We  don't  even  worry  about tracking the pathnames, or passing them down the call
       stack.
              int
              main(int argc, char **argv)
              {
                  for (;;)
                  {
                      int c = getopt(argc, argv, "o:");
                      if (c == EOF)
                          break;
                      switch (c)
                      {
                      case 'o':
                          explain_freopen_or_die(optarg, "w", stdout);
                          break;
       The fun part of this code is that libexplain can report errors including the pathname even if  you  don't
       explicitly re‐open stdout as is done here.  We don't even worry about tracking the file name.
                      default:
                          fprintf(stderr, "Usage: %ss [ -o <filename> ] <filename>...\n",
                              argv[0]);
                          return EXIT_FAILURE;
                      }
                  }
                  if (optind == argc)
                      process(stdin);
                  else
                  {
                      while (optind < argc)
                      {
                          FILE *fp = explain_fopen_or_die(argv[optind]++, "r");
                          process(fp);
                          explain_fclose_or_die(fp);
                      }
                  }
       The  standard  output  will be closed implicitly, but too late for an error report to be issued, so we do
       that here, just in case the buffered I/O hasn't written anything yet, and there is  an  ENOSPC  error  or
       something.
                  explain_fflush_or_die(stdout);
                  return EXIT_SUCCESS;
              }
       That's all.  Full error reporting, clear code.

   Rusty's Scale of Interface Goodness
       For  those  of  you  not familiar with it, Rusty Russel's “How Do I Make This Hard to Misuse?”  page is a
       must‐read for API designers.
       http://ozlabs.org/~rusty/index.cgi/tech/2008‐03‐30.html

       10. It's impossible to get wrong.

       Goals need to be set high, ambitiously high, lest you accomplish them and think you are finished when you
       are not.

       The  libexplain library detects bogus pointers and many other bogus system call parameters, and generally
       tries to avoid segfaults in even the most trying circumstances.

       The libexplain library is designed to be thread safe.  More real‐world use will likely reveal places this
       can be improved.

       The  biggest  problem is with the actual function names themselves.  Because C does not have name‐spaces,
       the libexplain library always uses an explain_ name prefix.  This is the traditional way  of  creating  a
       pseudo‐name‐space  in  order  to  avoid symbol conflicts.  However, it results in some unnatural‐sounding
       names.

       9. The compiler or linker won't let you get it wrong.

       A common mistake is to  use  explain_open  where  explain_open_or_die  was  intended.   Fortunately,  the
       compiler  will  often  issue  a type error at this point (e.g. can't assign const char * rvalue to an int
       lvalue).

       8. The compiler will warn if you get it wrong.

       If explain_rename is used when explain_rename_or_die was intended, this can cause  other  problems.   GCC
       has  a  useful  warn_unused_result  function attribute, and the libexplain library attaches it to all the
       explain_name function calls to produce a warning when you make  this  mistake.   Combine  this  with  gcc
       -Werror to promote this to level 9 goodness.

       7. The obvious use is (probably) the correct one.

       The  function  names  have been chosen to convey their meaning, but this is not always successful.  While
       explain_name_or_die and explain_name_on_error are fairly descriptive, the less‐used thread safe  variants
       are  harder  to decode.  The function prototypes help the compiler towards understanding, and the Doxygen
       comments in the header files help the user towards understanding.

       6. The name tells you how to use it.

       It is particularly important to read explain_name_or_die as “explain (name or die)”.  Using a  consistent
       explain_ name‐space prefix has some unfortunate side‐effects in the obviousness department, as well.

       The  order of words in the names also indicate the order of the arguments.  The argument lists always end
       with the same arguments as passed to the system call; all of them.  If _errno_ appears in the  name,  its
       argument  always precedes the system call arguments.  If _message_ appears in the name, its two arguments
       always come first.

       5. Do it right or it will break at runtime.

       The libexplain library detects bogus pointers and many other bogus system call parameters, and  generally
       tries  to  avoid  segfaults in even the most trying circumstances.  It should never break at runtime, but
       more real‐world use will no doubt improve this.

       Some error messages are aimed at developers and maintainers rather than end users,  as  this  can  assist
       with  bug  resolution.   Not  so much “break at runtime” as “be informative at runtime” (after the system
       call barfs).

       4. Follow common convention and you'll get it right.

       Because C does not have name‐spaces, the libexplain library always uses an explain_ name prefix.  This is
       the traditional way of creating a pseudo‐name‐space in order to avoid symbol conflicts.

       The  trailing  arguments of all the libexplain call are identical to the system call they are describing.
       This is intended to provide a consistent convention in common with the system calls themselves.

       3. Read the documentation and you'll get it right.

       The libexplain library aims to have complete Doxygen documentation for each and  every  public  API  call
       (and internally as well).

MESSAGE CONTENT

       Working  on  libexplain  is a bit like looking at the underside of your car when it is up on the hoist at
       the mechanic's.  There's some ugly stuff under there, plus mud and crud, and users rarely see it.  A good
       error  message needs to be informative, even for a user who has been fortunate enough not to have to look
       at the under‐side very often, and also informative for the mechanic listening to the  user's  description
       over the phone.  This is no easy task.

       Revisiting our first example, the code would like this if it uses libexplain:
              int fd = explain_open_or_die("some/thing", O_RDONLY, 0);
       will fail with an error message like this
              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

   Before Because
       It is possible to see the part of the message before  “because”  as  overly  technical  to  non‐technical
       users,  mostly  as  a  result of accurately printing the system call itself at the beginning of the error
       message.  And it looks like strace(1) output, for bonus geek points.
              open(pathname = "some/file", flags = O_RDONLY) failed, No such file or directory (2, ENOENT)
       This part of the error message is essential to the developer when he is writing  the  code,  and  equally
       important  to  the maintainer who has to read bug reports and fix bugs in the code.  It says exactly what
       failed.

       If this text is not presented to the user then the user cannot copy‐and‐paste it into a bug  report,  and
       if it isn't in the bug report the maintainer can't know what actually went wrong.

       Frequently  tech  staff  will use strace(1) or truss(1) to get this exact information, but this avenue is
       not open when reading bug reports.  The bug reporter's system is far far away, and,  by  now,  in  a  far
       different  state.   Thus,  this  information needs to be in the bug report, which means it must be in the
       error message.

       The system call representation also gives context to the rest  of  the  message.   If  need  arises,  the
       offending  system  call  argument  may  be  referred  to  by name in the explanation after “because”.  In
       addition, all strings are fully quoted and escaped C  strings,  so  embedded  newlines  and  non‐printing
       characters will not cause the user's terminal to go haywire.

       The system‐error is what comes out of strerror(2), plus the error symbol.  Impatient and expert sysadmins
       could stop reading at this point, but the  author's  experience  to  date  is  that  reading  further  is
       rewarding.   (If  it  isn't  rewarding,  it's  probably an area of libexplain that can be improved.  Code
       contributions are welcome, of course.)

   After Because
       This is the portion of the error message aimed at non‐technical users.  It looks beyond the simple system
       call arguments, and looks for something more specific.
              there is no "some" directory in the current directory
       This  portion  attempts to explain the proximal cause of the error in plain language, and it is here that
       internationalization is essential.

       In general, the policy is to include as much information as possible, so that the user doesn't need to go
       looking for it (and doesn't leave it out of the bug report).

   Internationalization
       Most  of  the  error  messages  in  the  libexplain  library  have  been internationalized.  There are no
       localizations as yet, so if you want the explanations in your native language, please contribute.

       The “most of” qualifier, above, relates to the fact that  the  proof‐of‐concept  implementation  did  not
       include  internationalization support.  The code base is being revised progressively, usually as a result
       of refactoring messages so that each error message string appears in the code exactly once.

       Provision has been made for languages that need to assemble the portions of
              system‐call failed, system‐error because explanation
       in different orders for correct grammar in localized error messages.

   Postmortem
       There are times when a program has yet to use libexplain, and you can't use strace(1) either.   There  is
       an  explain(1) command included with libexplain that can be used to decipher error messages, if the state
       of the underlying system hasn't changed too much.
              $ explain rename foo /tmp/bar/baz -e ENOENT
              rename(oldpath = "foo", newpath = "/tmp/bar/baz") failed, No such file or  directory  (2,  ENOENT)
              because there is no "bar" directory in the newpath "/tmp" directory
              $
       Note  how  the path ambiguity is resolved by using the system call argument name.  Of course, you have to
       know the error and the system call for explain(1) to be useful.  As an aside, this is  one  of  the  ways
       used by the libexplain automatic test suite to verify that libexplain is working.

   Philosophy
       “Tell me everything, including stuff I didn't know to look for.”

       The library is implemented in such a way that when statically linked, only the code you actually use will
       be linked.  This is achieved by having one function per source file, whenever feasible.

       When it is possible to supply more information, libexplain will do so.  The less the user  has  to  track
       down  for  themselves,  the  better.   This  means  that  UIDs are accompanied by the user name, GIDs are
       accompanied by the group name, PIDs are accompanied by the process name, file descriptors and streams are
       accompanied by the pathname, etc.

       When  resolving  paths,  if  a  path component does not exist, libexplain will look for similar names, in
       order to suggest alternatives for typographical errors.

       The libexplain library tries to use as little heap as possible, and  usually  none.   This  is  to  avoid
       perturbing the process state, as far as possible, although sometimes it is unavoidable.

       The  libexplain  library  attempts  to be thread safe, by avoiding global variables, keeping state on the
       stack as much as possible.  There is a single common message buffer, and the functions that  use  it  are
       documented as not being thread safe.

       The  libexplain  library  does not disturb a process's signal handlers.  This makes determining whether a
       pointer would segfault a challenge, but not impossible.

       When information is available via a system call as well as available through a /proc  entry,  the  system
       call  is  preferred.  This is to avoid disturbing the process's state.  There are also times when no file
       descriptors are available.

       The libexplain library is compiled with large file  support.   There  is  no  large/small  schizophrenia.
       Where  this  affects  the argument types in the API, and error will be issued if the necessary large file
       defines are absent.

       FIXME: Work is needed to make sure that file system quotas are handled in the code.  This applies to some
       getrlimit(2) boundaries, as well.

       There  are  cases  when  relatives  paths  are  uninformative.   For example: system daemons, servers and
       background processes.  In these cases, absolute paths are used in the error explanations.

PATH RESOLUTION

       Short version: see path_resolution(7).

       Long version: Most users have never heard of path_resolution(7), and many advanced users have never  read
       it.  Here is an annotated version:

   Step 1: Start of the resolution process
       If  the  pathname  starts  with  the  slash  (“/”)  character,  the starting lookup directory is the root
       directory of the calling process.

       If the pathname does not start with the slash(“/”)  character,  the  starting  lookup  directory  of  the
       resolution process is the current working directory of the process.

   Step 2: Walk along the path
       Set  the current lookup directory to the starting lookup directory.  Now, for each non‐final component of
       the pathname, where a component is a substring delimited by slash (“/”)  characters,  this  component  is
       looked up in the current lookup directory.

       If  the  process  does  not  have  search  permission on the current lookup directory, an EACCES error is
       returned ("Permission denied").
              open(pathname = "/home/archives/.ssh/private_key", flags =  O_RDONLY)  failed,  Permission  denied
              (13,   EACCES)   because   the   process   does   not  have  search  permission  to  the  pathname
              "/home/archives/.ssh" directory, the process effective GID  1000  "pmiller"  does  not  match  the
              directory  owner  1001  "archives"  so  the  owner  permission  mode  "rwx" is ignored, the others
              permission mode is "---", and the process is not privileged (does  not  have  the  DAC_READ_SEARCH
              capability)

       If the component is not found, an ENOENT error is returned ("No such file or directory").
              unlink(pathname = "/home/microsoft/rubbish") failed, No such file or directory (2, ENOENT) because
              there is no "microsoft" directory in the pathname "/home" directory

       There is also some support for users when they mis‐type pathnames,  making  suggestions  when  ENOENT  is
       returned:
              open(pathname  =  "/user/include/fcntl.h", flags = O_RDONLY) failed, No such file or directory (2,
              ENOENT) because there is no "user" directory in the pathname "/" directory, did you mean the "usr"
              directory instead?

       If   the   component   is  found,  but  is  neither  a directory nor a symbolic link, an ENOTDIR error is
       returned ("Not a directory").
              open(pathname = "/home/pmiller/.netrc/lca",  flags  =  O_RDONLY)  failed,  Not  a  directory  (20,
              ENOTDIR) because the ".netrc" regular file in the pathname "/home/pmiller" directory is being used
              as a directory when it is not

       If the component is found and is a directory, we set the current lookup directory to that directory,  and
       go to the next component.

       If the component is found and is a symbolic link (symlink), we first resolve this symbolic link (with the
       current lookup directory as starting lookup directory).  Upon error, that  error  is  returned.   If  the
       result is not a directory, an ENOTDIR error is returned.
              unlink(pathname  =  "/tmp/dangling/rubbish") failed, No such file or directory (2, ENOENT) because
              the "dangling" symbolic link in the pathname "/tmp" directory refers to "nowhere"  that  does  not
              exist
       If  the  resolution  of  the  symlink  is  successful  and returns a directory, we set the current lookup
       directory to that directory, and go to the  next  component.   Note  that  the  resolution  process  here
       involves  recursion.   In order to protect the kernel against stack overflow, and also to protect against
       denial of service, there are limits on the maximum recursion depth, and on the maximum number of symbolic
       links  followed.   An  ELOOP error is returned when the maximum is exceeded ("Too many levels of symbolic
       links").
              open(pathname = "/tmp/dangling", flags = O_RDONLY) failed, Too many levels of symbolic links  (40,
              ELOOP) because a symbolic link loop was encountered in pathname, starting at "/tmp/dangling"
       It  is  also  possible  to  get  an ELOOP or EMLINK error if there are too many symlinks, but no loop was
       detected.
              open(pathname = "/tmp/rabbit‐hole", flags = O_RDONLY) failed, Too many levels  of  symbolic  links
              (40, ELOOP) because too many symbolic links were encountered in pathname (8)
       Notice how the actual limit is also printed.

   Step 3: Find the final entry
       The  lookup  of  the  final  component  of  the  pathname goes just like that of all other components, as
       described in the previous step, with two differences:

       (i) The final component need not be a directory (at least as  far  as  the  path  resolution  process  is
           concerned.   It  may  have  to be a directory, or a non‐directory, because of the requirements of the
           specific system call).

       (ii)
           It is not necessarily an error if the final component is not found; maybe we are  just  creating  it.
           The  details  on  the  treatment of the final entry are described in the manual pages of the specific
           system calls.

       (iii)
           It is also possible to have a problem with the last component if it is a symbolic link and it  should
           not be followed.  For example, using the open(2) O_NOFOLLOW flag:
           open(pathname = "a‐symlink", flags = O_RDONLY | O_NOFOLLOW) failed, Too many levels of symbolic links
           (ELOOP) because O_NOFOLLOW was specified but pathname refers to a symbolic link

       (iv)
           It is common for users to make mistakes when typing pathnames.  The libexplain  library  attempts  to
           make suggestions when ENOENT is returned, for example:
           open(pathname  = "/usr/include/filecontrl.h", flags = O_RDONLY) failed, No such file or directory (2,
           ENOENT) because there is no "filecontrl.h" regular file in the pathname "/usr/include" directory, did
           you mean the "fcntl.h" regular file instead?

       (v) It is also possible that the final component is required to be something other than a regular file:
           readlink(pathname = "just‐a‐file", data = 0x7F930A50, data_size = 4097) failed, Invalid argument (22,
           EINVAL) because pathname is a regular file, not a symbolic link

       (vi)
           FIXME: handling of the "t" bit.

   Limits
       There are a number of limits with regards to pathnames and filenames.

       Pathname length limit
               There is a maximum length for pathnames.  If the pathname (or some intermediate pathname obtained
               while  resolving  symbolic  links) is too long, an ENAMETOOLONG error is returned ("File name too
               long").  Notice how the system limit is included in the error message.
               open(pathname = "very...long", flags = O_RDONLY) failed, File name too  long  (36,  ENAMETOOLONG)
               because pathname exceeds the system maximum path length (4096)

       Filename length limit
               Some Unix variants have a limit on the number of bytes in each path component.  Some of them deal
               with this  silently,  and  some  give  ENAMETOOLONG;  the  libexplain  library  uses  pathconf(3)
               _PC_NO_TRUNC  to  tell which.  If this error happens, the libexplain library will state the limit
               in the error message, the limit is obtained from pathconf(3) _PC_NAME_MAX.  Notice how the system
               limit is included in the error message.
               open(pathname  =  "system7/only-had-14-characters",  flags = O_RDONLY) failed, File name too long
               (36, ENAMETOOLONG) because "only-had-14-characters" component is longer  than  the  system  limit
               (14)

       Empty pathname
               In  the  original  Unix,  the  empty  pathname referred to the current directory.  Nowadays POSIX
               decrees that an empty pathname must not be resolved successfully.
               open(pathname = "", flags = O_RDONLY) failed, No such file or directory (2, ENOENT) because POSIX
               decrees that an empty pathname must not be resolved successfully

   Permissions
       The  permission  bits  of a file consist of three groups of three bits.  The first group of three is used
       when the effective user ID of the calling process equals the owner ID of the file.  The second  group  of
       three  is used when the group ID of the file either equals the effective group ID of the calling process,
       or is one of the supplementary group IDs of the calling process.  When neither holds, the third group  is
       used.
              open(pathname  =  "/etc/passwd",  flags = O_WRONLY) failed, Permission denied (13, EACCES) because
              the process does not have write permission to the "passwd" regular file  in  the  pathname  "/etc"
              directory, the process effective UID 1000 "pmiller" does not match the regular file owner 0 "root"
              so the owner permission mode "rw-" is ignored, the  others  permission  mode  is  "r--",  and  the
              process is not privileged (does not have the DAC_OVERRIDE capability)
       Some  considerable  space  is  given  to this explanation, as most users do not know that this is how the
       permissions system works.  In particular: the owner, group and other permissions are exclusive, they  are
       not “OR”ed together.

STRANGE AND INTERESTING SYSTEM CALLS

       The process of writing a specific error handler for each system call often reveals interesting quirks and
       boundary conditions, or obscure errno(3) values.

   ENOMEDIUM, No medium found
       The act of copying a CD was the source of the title for this paper.
              $ dd if=/dev/cdrom of=fubar.iso
              dd: opening “/dev/cdrom”: No medium found
              $
       The author wondered why his computer was telling him there is no such thing as a psychic  medium.   Quite
       apart  from  the  fact  that huge numbers of native English speakers are not even aware that “media” is a
       plural, let alone that “medium” is its singular, the string returned by strerror(3) for ENOMEDIUM  is  so
       terse as to be almost completely free of content.

       When  open(2) returns ENOMEDIUM it would be nice if the libexplain library could expand a little on this,
       based on the type of drive it is.  For example:
         ... because there is no disk in the floppy drive
         ... because there is no disc in the CD‐ROM drive
         ... because there is no tape in the tape drive
         ... because there is no memory stick in the card reader

       And so it came to pass...
              open(pathname = "/dev/cdrom", flags = O_RDONLY) failed, No medium found (123,  ENOMEDIUM)  because
              there does not appear to be a disc in the CD‐ROM drive
       The  trick,  that the author was previously unaware of, was to open the device using the O_NONBLOCK flag,
       which will allow you to open a drive with no medium in it.   You  then  issue  device  specific  ioctl(2)
       requests until you figure out what the heck it is.  (Not sure if this is POSIX, but it also seems to work
       that way in BSD and Solaris, according to the wodim(1) sources.)

       Note also the differing uses of “disk” and “disc” in context.  The CD standard originated in France,  but
       everything else has a “k”.

   EFAULT, Bad address
       Any  system  call that takes a pointer argument can return EFAULT.  The libexplain library can figure out
       which argument is at fault, and it does it without disturbing the process (or thread) signal handling.

       When available, the mincore(2) system call is used, to ask if the memory region is valid.  It can  return
       three  results:  mapped  but not in physical memory, mapped and in physical memory, and not mapped.  When
       testing the validity of a pointer, the first two are “yes” and the last one is “no”.

       Checking C strings are more difficult, because instead of a pointer and a size, we only have  a  pointer.
       To determine the size we would have to find the NUL, and that could segfault, catch‐22.

       To  work  around  this,  the  libexplain  library  uses the lstat(2) sysem call (with a known good second
       argument) to test C strings for validity.  A failure return && errno == EFAULT is  a  “no”,  and  anythng
       else is a “yes”.  This, of course limits strings to PATH_MAX characters, but that usually isn't a problem
       for the libexplain library, because that is almost always the longest strings it cares about.

   EMFILE, Too many open files
       This error occurs when a process already has the maximum number of file descriptors open.  If the  actual
       limit  is to be printed, and the libexplain library tries to, you can't open a file in /proc to read what
       it is.
              open_max = sysconf(_SC_OPEN_MAX);
       This one wan't so difficult, there is a sysconf(3) way of obtaining the limit.

   ENFILE, Too many open files in system
       This error occurs when the system limit on the total number of open files has been reached.  In this case
       there is no handy sysconf(3) way of obtain the limit.

       Digging deeper, one may discover that on Linux there is a /proc entry we could read to obtain this value.
       Catch‐22: we are out of file descriptors, so we can't open a file to read the limit.

       On Linux there is a system call to obtain it, but it has no [e]glibc wrapper function, so you have to all
       it very carefully:
              long
              explain_maxfile(void)
              {
              #ifdef __linux__
                  struct __sysctl_args args;
                  int32_t maxfile;
                  size_t maxfile_size = sizeof(maxfile);
                  int name[] = { CTL_FS, FS_MAXFILE };
                  memset(&args, 0, sizeof(struct __sysctl_args));
                  args.name = name;
                  args.nlen = 2;
                  args.oldval = &maxfile;
                  args.oldlenp = &maxfile_size;
                  if (syscall(SYS__sysctl, &args) >= 0)
                      return maxfile;
              #endif
                  return -1;
              }
       This permits the limit to be included in the error message, when available.

   EINVAL “Invalid argument” vs ENOSYS “Function not implemented”
       Unsupported  actions  (such  as  symlink(2)  on a FAT file system) are not reported consistently from one
       system call to the next.  It is possible to have either EINVAL or ENOSYS returned.

       As a result, attention must be paid to these error cases to get them right, particularly  as  the  EINVAL
       could also be referring to problems with one or more system call arguments.

   Note that errno(3) is not always set
       There  are  times  when it is necessary to read the [e]glibc sources to determine how and when errors are
       returned for some system calls.

       feof(3), fileno(3)
           It is often assumed that these functions cannot return an error.  This is only  true  if  the  stream
           argument is valid, however they are capable of detecting an invalid pointer.

       fpathconf(3), pathconf(3)
           The  return value of fpathconf(2) and pathconf(2) could legitimately be -1, so it is necessary to see
           if errno(3) has been explicitly set.

       ioctl(2)
           The return value of ioctl(2) could legitimately be -1, so it is necessary to see if errno(3) has been
           explicitly set.

       readdir(3)
           The  return  value  of readdir(3) is NULL for both errors and end‐of‐file.  It is necessary to see if
           errno(3) has been explicitly set.

       setbuf(3), setbuffer(3), setlinebuf(3), setvbuf(3)
           All but the last of these functions return void.  And setvbuf(3)  is  only  documented  as  returning
           “non‐zero” on error.  It is necessary to see if errno(3) has been explicitly set.

       strtod(3), strtol(3), strtold(3), strtoll(3), strtoul(3), strtoull(3)
           These  functions  return  0 on error, but that is also a legitimate return value.  It is necessary to
           see if errno(3) has been explicitly set.

       ungetc(3)
           While only a single character of backup is mandated by  the  ANSI  C  standard,  it  turns  out  that
           [e]glibc  permits more...  but that means it can fail with ENOMEM.  It can also fail with EBADF if fp
           is bogus.  Most difficult of all, if you pass EOF an error return occurs, but errno is not set.

       The libexplain library detects all of these errors correctly, even in cases where the  error  values  are
       poorly documented, if at all.

   ENOSPC, No space left on device
       When  this  error refers to a file on a file system, the libexplain library prints the mount point of the
       file system with the problem.  This can make the source of the error much clearer.
              write(fildes = 1 "example", data = 0xbfff2340, data_size = 5) failed, No space left on device (28,
              ENOSPC) because the file system containing fildes ("/home") has no more space for data
       As  more  special  device  support  is  added, error messages are expected to include the device name and
       actual size of the device.

   EROFS, Read‐only file system
       When this error refers to a file on a file system, the libexplain library prints the mount point  of  the
       file system with the problem.  This can make the source of the error much clearer.

       As more special device support is added, error messages are expected to include the device name and type.
              open(pathname  =  "/dev/fd0",  O_RDWR, 0666) failed, Read‐only file system (30, EROFS) because the
              floppy disk has the write protect tab set

       ...because a CD‐ROM is not writable
       ...because the memory card has the write protect tab set
       ...because the ½ inch magnetic tape does not have a write ring

   rename
       The rename(2) system call is used to change the location or name of a file, moving it between directories
       if required.  If the destination pathname already exists it will be atomically replaced, so that there is
       no point at which another process attempting to access it will find it missing.

       There are limitations, however: you can only rename a directory  on  top  of  another  directory  if  the
       destination directory is not empty.
              rename(oldpath  =  "foo",  newpath  =  "bar")  failed, Directory not empty (39, ENOTEMPTY) because
              newpath is not an empty directory; that is, it contains entries other than "." and ".."
       You can't rename a directory on top of a non‐directory, either.
              rename(oldpath = "foo", newpath = "bar") failed, Not a directory (20, ENOTDIR) because oldpath  is
              a directory, but newpath is a regular file, not a directory
       Nor is the reverse allowed
              rename(oldpath  = "foo", newpath = "bar") failed, Is a directory (21, EISDIR) because newpath is a
              directory, but oldpath is a regular file, not a directory

       This, of course, makes the libexplain library's job more complicated, because the unlink(2)  or  rmdir(2)
       system  call  is  called  implicitly by rename(2), and so all of the unlink(2) or rmdir(2) errors must be
       detected and handled, as well.

   dup2
       The dup2(2) system call is used to create a second file descriptor that references the same object as the
       first file descriptor.  Typically this is used to implement shell input and output redirection.

       The  fun  thing  is  that,  just as rename(2) can atomically rename a file on top of an existing file and
       remove the old file, dup2(2) can do this onto an already‐open file descriptor.

       Once again, this makes the libexplain library's job more complicated, because the close(2) system call is
       called implicitly by dup2(2), and so all of close(2)'s errors must be detected and handled, as well.

ADVENTURES IN IOCTL SUPPORT

       The  ioctl(2)  system  call provides device driver authors with a way to communicate with user‐space that
       doesn't fit within the existing kernel API.  See ioctl_list(2).

   Decoding Request Numbers
       From a cursory look at the ioctl(2) interface, there would appear to be a  large  but  finite  number  of
       possible  ioctl(2)  requests.   Each  different  ioctl(2) request is effectively another system call, but
       without any type‐safety at all - the compiler can't help a programmer get these right.  This was probably
       the motivation behind tcflush(3) and friends.

       The  initial  impression  is that you could decode ioctl(2) requests using a huge switch statement.  This
       turns out to be infeasible because one very rapidly discovers that it is impossible to include all of the
       necessary  system  headers  defining the various ioctl(2) requests, because they have a hard time playing
       nicely with each other.

       A deeper look reveals that there is a range of “private” request numbers, and device driver  authors  are
       encouraged  to  use them.  This means that there is a far larger possible set of requests, with ambiguous
       request numbers, than are immediately apparent.  Also, there are some historical ambiguities as well.

       We already knew that the switch was impractical, but now we know that to select the  appropriate  request
       name and explanation we must consider not only the request number but also the file descriptor.

       The  implementation  of  ioctl(2) support within the libexplain library is to have a table of pointers to
       ioctl(2) request descriptors.  Each of these descriptors includes an optional pointer to a disambiguation
       function.

       Each  request  is actually implemented in a separate source file, so that the necessary include files are
       relieved of the obligation to play nicely with others.

   Representation
       The philosophy behind the libexplain library is to provide as much information as possible, including  an
       accurate  representation  of  the  system  call.  In the case of ioctl(2) this means printing the correct
       request number (by name) and also a correct (or at least useful) representation of the third argument.

       The ioctl(2) prototype looks like this:
              int ioctl(int fildes, int request, ...);
       which should have your type‐safety alarms going off.  Internal to [e]glibc, this is turned into a variety
       of forms:
              int __ioctl(int fildes, int request, long arg);
              int __ioctl(int fildes, int request, void *arg);
       and the Linux kernel syscall interface expects
              asmlinkage long sys_ioctl(unsigned int fildes, unsigned int request, unsigned long arg);
       The  extreme variability of the third argument is a challenge, when the libexplain library tries to print
       a representation of that third argument.  However, once the request number has been  disambiguated,  each
       entry in the the libexplain library's ioctl table has a custom print_data function (OO done manually).

   Explanations
       There  are  fewer  problems  determining  the  explanation  to be used.  Once the request number has been
       disambiguated, each entry in the libexplain library's ioctl table has a custom print_explanation function
       (again, OO done manually).

       Unlike  section  2  and  section  3 system calls, most ioctl(2) requests have no errors documented.  This
       means, to give good error descriptions, it is necessary to read kernel sources to discover

       • what errno(3) values may be returned, and

       • the cause of each error.

       Because of the OO nature of function call dispatching withing the kernel, you need to  read  all  sources
       implementing  that  ioctl(2)  request,  not  just  the generic implementation.  It is to be expected that
       different kernels will have different error numbers and subtly different error causes.

   EINVAL vs ENOTTY
       The situation is even worse for ioctl(2) requests than for system calls,  with  EINVAL  and  ENOTTY  both
       being  used  to  indicate  that  an  ioctl(2)  request is inappropriate in that context, and occasionally
       ENOSYS, ENOTSUP and EOPNOTSUPP (meant to be used for sockets) as well.  There are comments in  the  Linux
       kernel  sources  that  seem  to indicate a progressive cleanup is in progress.  For extra chaos, BSD adds
       ENOIOCTL to the confusion.

       As a result, attention must be paid to these error cases to get them right, particularly  as  the  EINVAL
       could also be referring to problems with one or more system call arguments.

   intptr_t
       The  C99  standard  defines  an  integer  type  that is guaranteed to be able to hold any pointer without
       representation loss.

       The above function syscall prototype would be better written
              long sys_ioctl(unsigned int fildes, unsigned int request, intptr_t arg);
       The problem is the cognitive dissonance  induced  by  device‐specific  or  file‐system‐specific  ioctl(2)
       implementations, such as:
              long vfs_ioctl(struct file *filp, unsigned int cmd, unsigned long arg);
       The  majority of ioctl(2) requests actually have an int *arg third argument.  But having it declared long
       leads to code treating this as long *arg.  This is harmless on 32‐bits (sizeof(long) == sizeof(int))  but
       nasty  on  64‐bits  (sizeof(long) != sizeof(int)).  Depending on the endian‐ness, you do or don't get the
       value you expect, but you always get a memory scribble or stack scribble as well.

       Writing all of these as
              int ioctl(int fildes, int request, ...);
              int __ioctl(int fildes, int request, intptr_t arg);
              long sys_ioctl(unsigned int fildes, unsigned int request, intptr_t arg);
              long vfs_ioctl(struct file *filp, unsigned int cmd, intptr_t arg);
       emphasizes that the integer is only an integer to represent a quantity that is almost always an unrelated
       pointer type.

CONCLUSION

       Use libexplain, your users will like it.

       libexplain version 1.4
       Copyright (C) 2008, 2009, 2010, 2011, 2012, 2013, 2014 Peter Miller

AUTHOR

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

                                                                                              explain_lca2010(1)