1  .\" Copyright (c) 2006,2008 Joseph Koshy.  All rights reserved.
  2  .\"
  3  .\" Redistribution and use in source and binary forms, with or without
  4  .\" modification, are permitted provided that the following conditions
  5  .\" are met:
  6  .\" 1. Redistributions of source code must retain the above copyright
  7  .\"    notice, this list of conditions and the following disclaimer.
  8  .\" 2. Redistributions in binary form must reproduce the above copyright
  9  .\"    notice, this list of conditions and the following disclaimer in the
 10  .\"    documentation and/or other materials provided with the distribution.
 11  .\"
 12  .\" This software is provided by Joseph Koshy ``as is'' and
 13  .\" any express or implied warranties, including, but not limited to, the
 14  .\" implied warranties of merchantability and fitness for a particular purpose
 15  .\" are disclaimed.  in no event shall Joseph Koshy be liable
 16  .\" for any direct, indirect, incidental, special, exemplary, or consequential
 17  .\" damages (including, but not limited to, procurement of substitute goods
 18  .\" or services; loss of use, data, or profits; or business interruption)
 19  .\" however caused and on any theory of liability, whether in contract, strict
 20  .\" liability, or tort (including negligence or otherwise) arising in any way
 21  .\" out of the use of this software, even if advised of the possibility of
 22  .\" such damage.
 23  .\"
 24  .\" $Id$
 25  .\"
 26  .Dd June 11, 2006
 27  .Os
 28  .Dt ELF_ERRMSG 3
 29  .Sh NAME
 30  .Nm elf_errmsg ,
 31  .Nm elf_errno
 32  .Nd ELF library error message handling
 33  .Sh LIBRARY
 34  .Lb libelf
 35  .Sh SYNOPSIS
 36  .In libelf.h
 37  .Ft int
 38  .Fn elf_errno "void"
 39  .Ft "const char *"
 40  .Fn elf_errmsg "int error"
 41  .Sh DESCRIPTION
 42  When an error occurs during an ELF library API call, the library
 43  encodes the error using an error number and stores the error number
 44  internally for retrieval by the application at a later point of time.
 45  Error numbers may contain an OS supplied error code in addition to
 46  an ELF API specific error code.
 47  An error number value of zero indicates no error.
 48  .Pp
 49  Function
 50  .Fn elf_errno
 51  is used to retrieve the last error recorded by the ELF library.
 52  Invoking this function has the side-effect of resetting the
 53  ELF library's recorded error number to zero.
 54  .Pp
 55  The function
 56  .Fn elf_errmsg
 57  returns a null-terminated string with a human readable
 58  description of the error specified in argument
 59  .Ar error .
 60  A zero value for argument
 61  .Ar error
 62  retrieves the most recent error encountered by the ELF
 63  library.
 64  An argument value of -1 behaves identically, except that
 65  it guarantees a non-NULL return from
 66  .Fn elf_errmsg .
 67  .Sh RETURN VALUES
 68  Function
 69  .Fn elf_errno
 70  returns a non-zero value encoding the last error encountered
 71  by the ELF library, or zero if no error was encountered.
 72  .Pp
 73  Function
 74  .Fn elf_errmsg
 75  returns a pointer to library local storage for non-zero values
 76  of argument
 77  .Ar error .
 78  With a zero argument, the function will return a NULL pointer if no
 79  error had been encountered by the library, or will return a pointer to
 80  library local storage containing an appropriate message otherwise.
 81  .Sh EXAMPLES
 82  Clearing the ELF library's recorded error number can be accomplished
 83  by invoking
 84  .Fn elf_errno
 85  and discarding its return value.
 86  .Bd -literal -offset indent
 87  /* clear error */
 88  (void) elf_errno();
 89  .Ed
 90  .Pp
 91  Retrieving a human-readable description of the current error number
 92  can be done with the following snippet:
 93  .Bd -literal -offset indent
 94  int err;
 95  const char *errmsg;
 96  \&...
 97  err = elf_errno();
 98  if (err != 0)
 99  	errmsg = elf_errmsg(err);
100  .Ed
101  .Sh SEE ALSO
102  .Xr elf 3 ,
103  .Xr gelf 3
104  .Sh BUGS
105  Function
106  .Fn elf_errmsg
107  is not localized.