Updated references for error reporting functions.
authorFrank Mori Hess <fmhess@speakeasy.net>
Wed, 13 Feb 2008 20:13:39 +0000 (20:13 +0000)
committerFrank Mori Hess <fmhess@speakeasy.net>
Wed, 13 Feb 2008 20:13:39 +0000 (20:13 +0000)
doc/error_funcref.txt

index 1a3fa4d9ee9d8b31bc806ba2375f067ed5c3797b..133b4fc0a5cdfd39fb487af76563e725b58bc727 100644 (file)
@@ -6,8 +6,11 @@ Description:
  NULL, depending on the return type.  An internal library
  variable stores an error number, which can be retrieved with
  comedi_errno().  This error number can be converted to a
- human-readable form by the functions comedi_perror()
- and comedi_strerror().
+ human-readable form by the functions
+ <link linkend="func-ref-comedi-perror"><function>comedi_perror</function></link>
+ and
+ <link linkend="func-ref-comedi-strerror"><function>comedi_strerror</function></link>
+ .
 
  These functions are intended to mimic the behavior of the
  standard C library functions perror(), strerror(), and errno.
@@ -19,10 +22,6 @@ Description:
  the most recent comedilib error.  This integer may be used
  as the errnum parameter for comedi_strerror().
 
- Note that comedi_errno() is deliberately different than the
- variable errno.  This is to overcome difficulties in making
- errno thread-safe.
-
 Function: comedi_loglevel -- change Comedilib logging properties
 Retval: int
 Param: int loglevel
@@ -39,20 +38,42 @@ Description:
  disabled by default when Comedilib is compiled.
 
  The meaning of the loglevels is as follows:
-
- COMEDI_LOGLEVEL=0  Comedilib prints nothing.
-
- COMEDI_LOGLEVEL=1  (default) Comedilib prints error messages when
- there is a self-consistency error (i.e., an internal bug.)
-
- COMEDI_LOGLEVEL=2  Comedilib prints an error message when an invalid
- parameter is passed.
-
- COMEDI_LOGLEVEL=3  Comedilib prints an error message whenever an
- error is generated in the Comedilib library or in the C library,
- when called by Comedilib.
-
- COMEDI_LOGLEVEL=4  Comedilib prints a lot of junk.
+       <table frame="box" rules="all">
+               <tr>
+                       <th>Loglevel</th>
+                       <th>Behavior</th>
+               </tr>
+               <tr>
+                       <td>0</td>
+                       <td>Comedilib prints nothing.</td>
+               </tr>
+               <tr>
+                       <td>1</td>
+                       <td>
+                               (default) Comedilib prints error messages when
+                               there is a self-consistency error (i.e., an internal bug.)
+                       </td>
+               </tr>
+               <tr>
+                       <td>2</td>
+                       <td>
+                               Comedilib prints an error message when an invalid
+                               parameter is passed.
+                       </td>
+               </tr>
+               <tr>
+                       <td>3</td>
+                       <td>
+                               Comedilib prints an error message whenever an
+                               error is generated in the Comedilib library or in the C library,
+                               when called by Comedilib.
+                       </td>
+               </tr>
+               <tr>
+                       <td>4</td>
+                       <td>Comedilib prints a lot of junk.</td>
+               </tr>
+       </table>
 Returns:
  This function returns the previous loglevel.
 
@@ -63,9 +84,12 @@ Description:
  When a Comedilib function fails, it usually returns -1 or
  NULL, depending on the return type.  An internal library
  variable stores an error number, which can be retrieved with
- comedi_errno().  This error number can be converted to a
- human-readable form by the functions comedi_perror()
- and comedi_strerror().
+ <link linkend="func-ref-comedi-errno"><function>comedi_errno</function></link>
+ .  This error number can be converted to a
+ human-readable form by the functions
+ comedi_perror() or
+ <link linkend="func-ref-comedi-strerror"><function>comedi_strerror</function></link>
+ .
 
  These functions are intended to mimic the behavior of the
  standard C library functions perror(), strerror(), and errno.
@@ -78,15 +102,16 @@ Description:
  space, a description of the error condition, and a new line.
 
 Function: comedi_strerror -- return string describing Comedilib error code
-Retval: char *
+Retval: const char *
 Param: int errnum
 Description:
  When a Comedilib function fails, it usually returns -1 or
  NULL, depending on the return type.  An internal library
  variable stores an error number, which can be retrieved with
  comedi_errno().  This error number can be converted to a
- human-readable form by the functions comedi_perror()
- and comedi_strerror().
+ human-readable form by the functions
+ <link linkend="func-ref-comedi-perror"><function>comedi_perror</function></link>
+ or comedi_strerror().
 
  These functions are intended to mimic the behavior of the
  standard C library functions perror(), strerror(), and errno.
@@ -96,7 +121,9 @@ Description:
 
  The function comedi_strerror() returns a pointer to a
  character string
- describing the Comedilib error errnum.  The persistence
- of the returned pointer is undefined, and should not be trusted
- after the next Comedilib call.  An unrecognized error number will
+ describing the Comedilib error <parameter>errnum</parameter>.
+ The returned string may be
+ modified by a subsequent call to a strerr or perror function
+ (either the libc or Comedilib versions).
+ An unrecognized error number will
  return a pointer to the string "undefined error", or similar.