diff --git a/modules/libcom/src/error/errlog.h b/modules/libcom/src/error/errlog.h index 425e78ac6..02f2c0816 100644 --- a/modules/libcom/src/error/errlog.h +++ b/modules/libcom/src/error/errlog.h @@ -11,6 +11,20 @@ #ifndef INC_errlog_H #define INC_errlog_H +/** \file errlog.h + * \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 + * 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 + * `The C Programming Language ANSI C Edition` by Kernighan and Ritchie. + * + */ + #include #include #include @@ -22,8 +36,15 @@ extern "C" { #endif +/** + * errlogListener function type. + * + * This is used when adding or removing log listeners in ::errlogAddListener + * and ::errlogRemoveListeners. + */ typedef void (*errlogListener)(void *pPrivate, const char *message); +/** errlog severity enums */ typedef enum { errlogInfo, errlogMinor, @@ -45,37 +66,171 @@ LIBCOM_API extern int errVerbose; LIBCOM_API extern const char * errlogSevEnumString[]; #endif -/* errMessage is a macro so it can get the file and line number */ +/** + * 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 file 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 + * + * \param S Status code + * \param PM The message to print + */ #define errMessage(S, PM) \ errPrintf(S, __FILE__, __LINE__, "%s", PM) -/* epicsPrintf and epicsVprintf are old names for errlog routines*/ + +/** epicsPrintf is an old name for errlog routines */ #define epicsPrintf errlogPrintf + +/** epicsVprintf is an old name for errlog routines */ #define epicsVprintf errlogVprintf +/** + * 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. + */ 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. + */ 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=` 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 pFormat 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=` 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 pFormat The message to log or print + * \param pvar va_list + * \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 + */ LIBCOM_API const char * errlogGetSevEnumString(errlogSevEnum severity); + +/** + * Sets the severity to log + * + * \param severity The severity from ::errlogSevEnum + */ LIBCOM_API void errlogSetSevToLog(errlogSevEnum severity); + +/** + * Gets the current severity to log + * + * \return ::errlogSevEnum + */ LIBCOM_API errlogSevEnum errlogGetSevToLog(void); +/** + * Any code can receive errlog message. This function will add a listener callback. + * + * \param listener Function pointer of type ::errlogListener + * \param pPrivate This will be passed as the first argument of listener() + */ LIBCOM_API void errlogAddListener(errlogListener listener, void *pPrivate); + +/** + * This function will remove a listener callback. + * + * \param listener Function pointer of type ::errlogListener + * \param pPrivate This will be passed as the first argument of listener() + */ LIBCOM_API int errlogRemoveListeners(errlogListener listener, void *pPrivate); +/** + * Normally the errlog system displays all messages on the console. + * 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) + * \return 0 + */ LIBCOM_API int eltc(int yesno); + +/** + * Sets a new stream to write the messages to + * + * \param stream Pointer to file handle + * \return 0 + */ LIBCOM_API int errlogSetConsole(FILE *stream); +/** + * Can be used to initialize the error logging system with a larger buffer. The default buffer 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 buffer and maximum message size. + * The default buffer 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 flushed from the queue. */ LIBCOM_API void errlogFlush(void); +/** + * Routine errPrintf is normally called as follows: + * `errPrintf(status, __FILE__, __LINE__,"",...); ` + * + * Where status is defined as: + * - 0: Find latest vxWorks or Unix error. + * - -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 file 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. + */ LIBCOM_API void errPrintf(long status, const char *pFileName, int lineno, const char *pformat, ...) EPICS_PRINTF_STYLE(4,5); @@ -83,6 +238,13 @@ LIBCOM_API int errlogPrintfNoConsole(const char *pformat, ...) EPICS_PRINTF_STYLE(1,2); LIBCOM_API int errlogVprintfNoConsole(const char *pformat,va_list pvar); +/** + * Lookup the status code and return the string value in pBuf + * + * \param status The status code to lookup + * \param pBuf The char buffer to write the string value into + * \param bufLength The max size of pBuf + */ LIBCOM_API void errSymLookup(long status, char *pBuf, size_t bufLength); #ifdef __cplusplus