From: Ian Abbott Date: Wed, 9 May 2012 13:16:23 +0000 (+0100) Subject: doc/error_funcref.txt: Some DocBook mark-up changes. X-Git-Url: http://git.tremily.us/?p=comedilib.git;a=commitdiff_plain;h=054ceeb77e531a9f67429332288af38853555411 doc/error_funcref.txt: Some DocBook mark-up changes. --- diff --git a/doc/error_funcref.txt b/doc/error_funcref.txt index 5872802..30edb9a 100644 --- a/doc/error_funcref.txt +++ b/doc/error_funcref.txt @@ -3,128 +3,143 @@ Function: comedi_errno -- number of last Comedilib error Retval: int Param: void 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 + 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 by calling + comedi_errno This error number can be converted to a human-readable form by the functions - comedi_perror + comedi_perror and - comedi_strerror - . + comedi_strerror. These functions are intended to mimic the behavior of the - standard C library functions perror(), strerror(), and errno. + standard C library functions perror, + strerror, and errno. In particular, Comedilib functions sometimes return an error that is generated inside the C library; the comedi error message in this case is the same as the C library. - The function comedi_errno() returns an integer describing - the most recent comedilib error. This integer may be used - as the errnum parameter for comedi_strerror(). + The function comedi_errno returns an integer describing + the most recent Comedilib error. This integer may be used + as the errnum parameter for + comedi_strerror. Function: comedi_loglevel -- change Comedilib logging properties Retval: int Param: int loglevel Description: This function affects the output of debugging and error messages - from Comedilib. By increasing the loglevel, additional debugging + from Comedilib. By increasing the log level loglevel, additional debugging information will be printed. Error and debugging messages are - printed to the stream stderr. + printed to the standard error output stream stderr. The default loglevel can be set by using the environment variable - COMEDI_LOGLEVEL. The default loglevel is 1. + COMEDI_LOGLEVEL. The default log level is 1. In order to conserve resources, some debugging information is disabled by default when Comedilib is compiled. - The meaning of the loglevels is as follows: - - - - - - - - - - - - - - - - - - - - - - - - - -
LoglevelBehavior
0Comedilib prints nothing.
1 - (default) Comedilib prints error messages when - there is a self-consistency error (i.e., an internal bug.) -
2 - Comedilib prints an error message when an invalid - parameter is passed. -
3 - Comedilib prints an error message whenever an - error is generated in the Comedilib library or in the C library, - when called by Comedilib. -
4Comedilib prints a lot of junk.
+ The meaning of the log levels is as follows: + + + + + + + Loglevel + Behavior + + + + + 0 + Comedilib prints nothing. + + + 1 + + (default) Comedilib prints error messages when + there is a self-consistency error (i.e., an internal bug.) + + + + 2 + + Comedilib prints an error message when an invalid + parameter is passed. + + + + 3 + + Comedilib prints an error message whenever an + error is generated in the Comedilib library or in the C library, + when called by Comedilib. + + + + 4 + Comedilib prints a lot of junk. + + + + Returns: - This function returns the previous loglevel. + This function returns the previous log level. Function: comedi_perror -- print a Comedilib error message Retval: void Param: const char * s Description: - When a Comedilib function fails, it usually returns -1 or - NULL, depending on the return type. An internal library + 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 + comedi_errno. + This error number can be converted to a human-readable form by the functions - comedi_perror() or - comedi_strerror - . + comedi_perror or + comedi_strerror. These functions are intended to mimic the behavior of the - standard C library functions perror(), strerror(), and errno. + standard C library functions perror, + strerror, and errno. In particular, Comedilib functions sometimes return an error that is generated inside the C library; the comedi error message in this case is the same as the C library. - The function comedi_perror() prints an error message to stderr. - The error message consists of the argument string, a colon, a + The function comedi_perror prints an error message to + the standard error output stream stderr. + The error message consists of the argument string + s, a colon, a space, a description of the error condition, and a new line. Function: comedi_strerror -- return string describing Comedilib error code 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 + 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 + comedi_errno. + This error number can be converted to a human-readable form by the functions - comedi_perror - or comedi_strerror(). + comedi_perror + or comedi_strerror. These functions are intended to mimic the behavior of the - standard C library functions perror(), strerror(), and errno. + standard C library functions perror, + strerror, and errno. In particular, Comedilib functions sometimes return an error that is generated inside the C library; the comedi error message in this case is the same as the C library. - The function comedi_strerror() returns a pointer to a + The function comedi_strerror returns a pointer to a character string - describing the Comedilib error errnum. + describing the Comedilib error errnum. The returned string may be - modified by a subsequent call to a strerr or perror function - (either the libc or Comedilib versions). + 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. + return a pointer to the string undefined error, or similar.