errlog.h

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.

Defines

errMessage(S, PM)

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 message to print should not include a newline as one is added implicitly.

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

Parameters:

  • S – Status code

  • PM – The message to print

epicsPrintf

epicsPrintf is an old name for errlog routines

epicsVprintf

epicsVprintf is an old name for errlog routines

ANSI_ESC_RED
ANSI_ESC_GREEN
ANSI_ESC_YELLOW
ANSI_ESC_BLUE
ANSI_ESC_MAGENTA
ANSI_ESC_CYAN
ANSI_ESC_BOLD
ANSI_ESC_UNDERLINE
ANSI_ESC_RESET
ANSI_RED(STR)
ANSI_GREEN(STR)
ANSI_YELLOW(STR)
ANSI_BLUE(STR)
ANSI_MAGENTA(STR)
ANSI_CYAN(STR)
ANSI_BOLD(STR)
ANSI_UNDERLINE(STR)
ERL_ERROR
ERL_WARNING

Typedefs

typedef void (*errlogListener)(void *pPrivate, const char *message)

errlogListener function type.

This is used when adding or removing log listeners in errlogAddListener and errlogRemoveListeners.

Enums

enum errlogSevEnum

errlog severity enums

Values:

enumerator errlogInfo
enumerator errlogMinor
enumerator errlogMajor
enumerator errlogFatal

Functions

int errlogPrintf(const char *pformat, ...)

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.

int errlogVprintf(const char *pformat, va_list pvar)

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.

int errlogSevPrintf(const errlogSevEnum severity, const char *pformat, ...)

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.

Parameters:

  • severity – One of the severity enums from errlogSevEnum

  • pformat – The message to log or print

Returns:

int Consult printf documentation in C standard library

int errlogSevVprintf(const errlogSevEnum severity, const char *pformat, va_list pvar)

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.

Parameters:

  • severity – One of the severity enums from errlogSevEnum

  • pformat – The message to log or print

  • pvar – va_list

Returns:

int Consult printf documentation in C standard library

int errlogMessage(const char *message)

Sends message to the errlog task.

Parameters:

message – The message to send

const char *errlogGetSevEnumString(errlogSevEnum severity)

Gets the string value of severity.

Parameters:

severity – The severity from errlogSevEnum

Returns:

The string value

void errlogSetSevToLog(errlogSevEnum severity)

Sets the severity to log

Parameters:

severity – The severity from errlogSevEnum

errlogSevEnum errlogGetSevToLog(void)

Gets the current severity to log

Returns:

errlogSevEnum

void errlogAddListener(errlogListener listener, void *pPrivate)

Any code can receive errlog message. This function will add a listener callback.

Parameters:

  • listener – Function pointer of type errlogListener

  • pPrivate – This will be passed as the first argument of listener()

int errlogRemoveListeners(errlogListener listener, void *pPrivate)

This function will remove a listener callback.

Since

7.0.8 Safe to call from a listener callback.

Parameters:

  • listener – Function pointer of type errlogListener

  • pPrivate – This will be passed as the first argument of listener()

int eltc(int yesno)

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.

Parameters:

yesno – (0=No, 1=Yes)

Returns:

0

int errlogSetConsole(FILE *stream)

Sets a new stream to write the messages to

Parameters:

stream – Pointer to file handle

Returns:

0

int errlogInit(int bufsize)

Can be used to initialize the error logging system with a larger buffer. The default buffer size is 1280 bytes.

Parameters:

bufsize – The desired buffer size

int errlogInit2(int bufsize, int maxMsgSize)

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.

Parameters:

  • bufsize – The desired buffer size

  • maxMsgSize – The desired max message size

void errlogFlush(void)

Wakes up the errlog task and then waits until all messages are flushed from the queue.

void errPrintf(long status, const char *pFileName, int lineno, const char *pformat, ...)

Routine errPrintf is normally called as follows: errPrintf(status, __FILE__, __LINE__, "<fmt>", ...);

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

The remaining arguments are just like the arguments to the C printf routine. errVerbose determines if the filename and line number are shown.

Parameters:

  • status – See above

  • pFileName – As shown or NULL if the file name and line number should not be printed.

  • lineno – As shown

  • pformat – The message to log or print

int errlogPrintfNoConsole(const char *pformat, ...)
int errlogVprintfNoConsole(const char *pformat, va_list pvar)
void errSymLookup(long status, char *pBuf, size_t bufLength)

Lookup the status code and return the string value in pBuf

Parameters:

  • status – The status code to lookup

  • pBuf – The char buffer to write the string value into

  • bufLength – The max size of pBuf

Variables

int errVerbose

Boolean to control whether some messages include more detail

const char *errlogSevEnumString[]

String representation of errlog severity values