@ -15,14 +15,14 @@
* \brief Functions for interacting with the errlog task
*
* This file contains functions for passing error messages with varying severity,
* registering and un-registering listeners and modifying the log buffer size and
* registering and un-registering listeners and modifying the log buffer size and
* max message size.
*
* Some of these functions are similar to the standard C library functions printf
* and vprintf. For details on the arguments and return codes it is useful to consult
* any book that describes the standard C library such as
* and vprintf. For details on the arguments and return codes it is useful to consult
* any book that describes the standard C library such as
* `The C Programming Language ANSI C Edition` by Kernighan and Ritchie.
*
*
*/
# include <stdarg.h>
@ -37,9 +37,9 @@ extern "C" {
# endif
/**
* errlogListener function type.
*
* This is used when adding or removing log listeners in ::errlogAddListener
* errlogListener function type.
*
* This is used when adding or removing log listeners in ::errlogAddListener
* and ::errlogRemoveListeners.
*/
typedef void ( * errlogListener ) ( void * pPrivate , const char * message ) ;
@ -52,6 +52,7 @@ typedef enum {
errlogFatal
} errlogSevEnum ;
/** Boolean to control whether some messages include more detail */
LIBCOM_API extern int errVerbose ;
@ -63,18 +64,19 @@ LIBCOM_API extern int errVerbose;
" fatal "
} ;
# else
/** String representation of errlog severity values */
LIBCOM_API extern const char * errlogSevEnumString [ ] ;
# endif
/**
* errMessage is a macro so it can get the file and line number. It prints the message,
* the status symbol and string values, and the name of the task which invoked errMessage.
* It also prints the name of the source fi le and the line number from which the call was issued.
/**
* errMessage is a macro so it can get the file and line number. It prints the message,
* the status symbol and string values, and the name of the task which invoked errMessage.
* It also prints the name of the source fi le and the line number from which the call was issued.
*
* The status code used for the 1st argument is:
* - 0: Find latest vxWorks or Unix error (errno value).
* - -1: Don’ t report status.
* - Other: Use this status code and lookup the string value
* - -1: Don' t report status.
* - Other: Use this status code and lookup the string value
*
* \param S Status code
* \param PM The message to print
@ -90,58 +92,58 @@ LIBCOM_API extern int errVerbose;
/**
* errlogPrintf is like the printf function provided by the standard C library, except
* that the output is sent to the errlog task. Unless configured not to, the output
* will appear on the console as well.
* that the output is sent to the errlog task. Unless configured not to, the output
* will appear on the console as well.
*/
LIBCOM_API int errlogPrintf ( const char * pformat , . . . )
EPICS_PRINTF_STYLE ( 1 , 2 ) ;
/**
* errlogVprintf is like the vprintf function provided by the standard C library, except
* that the output is sent to the errlog task. Unless configured not to, the output
* will appear on the console as well.
* that the output is sent to the errlog task. Unless configured not to, the output
* will appear on the console as well.
*/
LIBCOM_API int errlogVprintf ( const char * pformat , va_list pvar ) ;
/**
* This function is like ::errlogPrintf except that it adds the severity to the beginning
* of the message in the form `sevr=<value>` where value is one of the enumerated
* severities in ::errlogSevEnum. Also the message is suppressed if severity is less than
* the current severity to suppress.
*
* This function is like ::errlogPrintf except that it adds the severity to the beginning
* of the message in the form `sevr=<value>` where value is one of the enumerated
* severities in ::errlogSevEnum. Also the message is suppressed if severity is less than
* the current severity to suppress.
*
* \param severity One of the severity enums from ::errlogSevEnum
* \param pF ormat The message to log or print
* \return int Consult printf documentation in C standard library
* \param pf ormat The message to log or print
* \return int Consult printf documentation in C standard library
*/
LIBCOM_API int errlogSevPrintf ( const errlogSevEnum severity ,
const char * pformat , . . . ) EPICS_PRINTF_STYLE ( 2 , 3 ) ;
/**
* This function is like ::errlogVprintf except that it adds the severity to the beginning
* of the message in the form `sevr=<value>` where value is one of the enumerated
* severities in ::errlogSevEnum. Also the message is suppressed if severity is less than
* the current severity to suppress. If epicsThreadIsOkToBlock is true, which is
* This function is like ::errlogVprintf except that it adds the severity to the beginning
* of the message in the form `sevr=<value>` where value is one of the enumerated
* severities in ::errlogSevEnum. Also the message is suppressed if severity is less than
* the current severity to suppress. If epicsThreadIsOkToBlock is true, which is
* true during iocInit, errlogSevVprintf does NOT send output to the
* errlog task.
*
*
* \param severity One of the severity enums from ::errlogSevEnum
* \param pF ormat The message to log or print
* \param pf ormat The message to log or print
* \param pvar va_list
* \return int Consult printf documentation in C standard library
* \return int Consult printf documentation in C standard library
*/
LIBCOM_API int errlogSevVprintf ( const errlogSevEnum severity ,
const char * pformat , va_list pvar ) ;
/**
/**
* Sends message to the errlog task.
*
*
* \param message The message to send
*/
LIBCOM_API int errlogMessage ( const char * message ) ;
/**
* Gets the string value of severity.
*
*
* \param severity The severity from ::errlogSevEnum
* \return The string value
*/
@ -180,7 +182,7 @@ LIBCOM_API int errlogRemoveListeners(errlogListener listener,
/**
* Normally the errlog system displays all messages on the console.
* During error message storms this function can be used to suppress console messages.
* During error message storms this function can be used to suppress console messages.
* A argument of 0 suppresses the messages, any other value lets messages go to the console.
*
* \param yesno (0=No, 1=Yes)
@ -197,39 +199,40 @@ LIBCOM_API int eltc(int yesno);
LIBCOM_API int errlogSetConsole ( FILE * stream ) ;
/**
* Can be used to initialize the error logging system with a larger buff er. The default buff er size is 1280 bytes.
* Can be used to initialize the error logging system with a larger buff er. The default buff er size is 1280 bytes.
*
* \param bufsize The desired buffer size
*/
LIBCOM_API int errlogInit ( int bufsize ) ;
/**
* errlogInit2 can be used to initialize the error logging system with a larger buff er and maximum message size.
* The default buff er size is 1280 bytes, and the default maximum message size is 256.
* errlogInit2 can be used to initialize the error logging system with a larger buff er and maximum message size.
* The default buff er size is 1280 bytes, and the default maximum message size is 256.
*
* \param bufsize The desired buffer size
* \param maxMsgSize The desired max message size
*/
LIBCOM_API int errlogInit2 ( int bufsize , int maxMsgSize ) ;
/** Wakes up the errlog task and then waits until all messages are fl ushed from the queue. */
/** Wakes up the errlog task and then waits until all messages are fl ushed from the queue. */
LIBCOM_API void errlogFlush ( void ) ;
/**
* Routine errPrintf is normally called as follows:
* `errPrintf(status, __FILE__, __LINE__,"<fmt>",...); `
*
* Where status is defi ned as:
* `errPrintf(status, __FILE__, __LINE__, "<fmt>", ...); `
*
* Where status is defi ned as:
* - 0: Find latest vxWorks or Unix error.
* - -1: Don’ t report status.
* - Other: Use this status code and lookup the string value
*
* - -1: Don' t report status.
* - Other: Use this status code and lookup the string value
*
* \param status See above
* \param __FILE__ As shown or NULL if the fi le name and line number should not be printed.
* \param __LINE__ As shown
*
* The remaining arguments are just like the arguments to the C printf routine.
* ::errVerbose determines if the filename and line number are shown .
* \param pFileName As shown or NULL if the fi le name and line number should not be printed.
* \param lineno As shown
* \param pformat The message to log or print
*
* The remaining arguments are just like the arguments to the C printf routine .
* ::errVerbose determines if the filename and line number are shown.
*/
LIBCOM_API void errPrintf ( long status , const char * pFileName , int lineno ,
const char * pformat , . . . ) EPICS_PRINTF_STYLE ( 4 , 5 ) ;