doc/error_funcref.txt

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