doc/error_funcref.txt

   1 Error reporting
   2 Function: comedi_errno -- number of last Comedilib error
   3 Retval: int
   4 Param: void
   5 Description:
   6  When a Comedilib function fails, it usually returns -1 or
   7  NULL, depending on the return type.  An internal library
   8  variable stores an error number, which can be retrieved with
   9  comedi_errno().  This error number can be converted to a
  10  human-readable form by the functions
  11  <link linkend="func-ref-comedi-perror"><function>comedi_perror</function></link>
  12  and
  13  <link linkend="func-ref-comedi-strerror"><function>comedi_strerror</function></link>
  14  .
  15
  16  These functions are intended to mimic the behavior of the
  17  standard C library functions perror(), strerror(), and errno.
  18  In particular, Comedilib functions sometimes return an error
  19  that is generated inside the C library; the comedi error
  20  message in this case is the same as the C library.
  21
  22  The function comedi_errno() returns an integer describing
  23  the most recent comedilib error.  This integer may be used
  24  as the errnum parameter for comedi_strerror().
  25
  26 Function: comedi_loglevel -- change Comedilib logging properties
  27 Retval: int
  28 Param: int loglevel
  29 Description:
  30  This function affects the output of debugging and error messages
  31  from Comedilib.  By increasing the loglevel, additional debugging
  32  information will be printed.  Error and debugging messages are
  33  printed to the stream stderr.
  34
  35  The default loglevel can be set by using the environment variable
  36  COMEDI_LOGLEVEL.  The default loglevel is 1.
  37
  38  In order to conserve resources, some debugging information is
  39  disabled by default when Comedilib is compiled.
  40
  41  The meaning of the loglevels is as follows:
  42         <table frame="box" rules="all">
  43                 <tr>
  44                         <th>Loglevel</th>
  45                         <th>Behavior</th>
  46                 </tr>
  47                 <tr>
  48                         <td>0</td>
  49                         <td>Comedilib prints nothing.</td>
  50                 </tr>
  51                 <tr>
  52                         <td>1</td>
  53                         <td>
  54                                 (default) Comedilib prints error messages when
  55                                 there is a self-consistency error (i.e., an internal bug.)
  56                         </td>
  57                 </tr>
  58                 <tr>
  59                         <td>2</td>
  60                         <td>
  61                                 Comedilib prints an error message when an invalid
  62                                 parameter is passed.
  63                         </td>
  64                 </tr>
  65                 <tr>
  66                         <td>3</td>
  67                         <td>
  68                                 Comedilib prints an error message whenever an
  69                                 error is generated in the Comedilib library or in the C library,
  70                                 when called by Comedilib.
  71                         </td>
  72                 </tr>
  73                 <tr>
  74                         <td>4</td>
  75                         <td>Comedilib prints a lot of junk.</td>
  76                 </tr>
  77         </table>
  78 Returns:
  79  This function returns the previous loglevel.
  80
  81 Function: comedi_perror -- print a Comedilib error message
  82 Retval: void
  83 Param: const char * s
  84 Description:
  85  When a Comedilib function fails, it usually returns -1 or
  86  NULL, depending on the return type.  An internal library
  87  variable stores an error number, which can be retrieved with
  88  <link linkend="func-ref-comedi-errno"><function>comedi_errno</function></link>
  89  .  This error number can be converted to a
  90  human-readable form by the functions
  91  comedi_perror() or
  92  <link linkend="func-ref-comedi-strerror"><function>comedi_strerror</function></link>
  93  .
  94
  95  These functions are intended to mimic the behavior of the
  96  standard C library functions perror(), strerror(), and errno.
  97  In particular, Comedilib functions sometimes return an error
  98  that is generated inside the C library; the comedi error
  99  message in this case is the same as the C library.
 100
 101  The function comedi_perror() prints an error message to stderr.
 102  The error message consists of the argument string, a colon, a
 103  space, a description of the error condition, and a new line.
 104
 105 Function: comedi_strerror -- return string describing Comedilib error code
 106 Retval: const char *
 107 Param: int errnum
 108 Description:
 109  When a Comedilib function fails, it usually returns -1 or
 110  NULL, depending on the return type.  An internal library
 111  variable stores an error number, which can be retrieved with
 112  comedi_errno().  This error number can be converted to a
 113  human-readable form by the functions
 114  <link linkend="func-ref-comedi-perror"><function>comedi_perror</function></link>
 115  or comedi_strerror().
 116
 117  These functions are intended to mimic the behavior of the
 118  standard C library functions perror(), strerror(), and errno.
 119  In particular, Comedilib functions sometimes return an error
 120  that is generated inside the C library; the comedi error
 121  message in this case is the same as the C library.
 122
 123  The function comedi_strerror() returns a pointer to a
 124  character string
 125  describing the Comedilib error <parameter>errnum</parameter>.
 126  The returned string may be
 127  modified by a subsequent call to a strerr or perror function
 128  (either the libc or Comedilib versions).
 129  An unrecognized error number will
 130  return a pointer to the string "undefined error", or similar.