Updated references for error reporting functions.

This commit is contained in:
Frank Mori Hess 2008-02-13 20:13:39 +00:00
parent 7eb7a64566
commit d127a63155

View 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.