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