Error Logging System

The error logging system provides:

Error message routines that can be called by ioc code.
Provision for multiple system wide error loggers..
A task (errlog) that handles the messages generated by the client routines. It displays messages on the target console and also gives them to any registered system wide error loggers.
iocLog: A system wide error logger that writes all error message to a file.

Overview

The error message routines can be called by any non-interrupt level code.
Task errlog manages the messages. Messages are placed in a message queue, which is read by the errlog task. The message queue uses a fixed block of memory to hold all messages. When the message queue is full additional messages are rejected but a count of missed messages is kept. The next time the message queue empties an extra message about the missed messages is generated.
The maximum message size is 256 characters. If a message is longer, the message is truncated and a message explaining that it was truncated is appended. There is a chance that long messages corrupt memory. This only happens if client code is defective. Long messages most likely result from "%s" formats with a bad string argument.
The error message routines are partially implemented on the host. The host version just calls fprintf or vfprintf instead of using a separate task and a message queue. Thus host messages are NOT sent to a system wide error logger.

A note from Marty

Date: Tue, 05 Oct 2004
From: Marty Kraimer 
Cc: tech-talk@aps.anl.gov
Subject: Re: Long Error Message

errlog allows a maximum message size of 256 characters.
It allows an extra 256 characters in an internal buffer.
Until extra is > 256 there is no buffer overflow.

Thus the following error message (at iocInit time) does not actually cause a problem.
>errlog: A message overran buffer by 3. This is VERY bad

In 3.14 errlog has been modified so that a buffer overflow can not occur.

Client Routines

Basic Routines

typedef enum {
    errlogInfo,errlogMinor,errlogMajor,errlogFatal
}errlogSevEnum;

int errlogPrintf(const char *pformat, ...);
int errlogVprintf(const char *pformat,va_list pvar);

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

int errlogMessage( const char *message);

char * errlogGetSevEnumString(const errlogSevEnum severity);

void errlogSetSevToLog(const errlogSevEnum severity );
errlogSevEnum errlogGetSevToLog(void);

errlogPrintf and errlogVprintf act just like printf and vprintf.

errlogSevPrintf and errlogSevVprintf are similar except that they also add the severity to the beginning of the message in the form "sevr=<value>" where value is on of "info, minor, major, fatal". Also the message is suppressed if severity is less than the current severity to suppress.

errlogMessage just logs message.

errlogGetSevEnumString gets the string value of severity.

errlogSetSevToLog sets the severity to log. errlogGetSevToLog gets the current severity to log.

Status Routines

void errMessage(long status, char *message);

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

 errPrintf(status,__FILE__, __LINE__,"<format>",...)

Obsolete Routines

int epicsPrintf(const char *pformat, ...);
int epicsVprintf(const char *pformat,va_list pvar);

Add and Remove Log Listener

typedef void(*errlogListener) (const char *message);
void errlogAddListener(errlogListener listener);
void errlogRemoveListener(errlogListener listener);

target console routines

void eltc(int yesno); /* error log to console (0 or 1) */
void errlogInit(int bufsize);

eltc determines if errlog task writes message to the console. If error messages storms are occuring the command can be used to suppress the messages. A argument of 0 suppresses the messages and any other value lets the message go to the console.

errlogInit can be used to initialize the error logging system with a larger buffer. The default is 1280 bytes. An extra MAX_MESSAGE_SIZE (currently 256) bytes are allocated but never used. This is a small extra protection against long error messages.

iocLog

This consists of two modules: iocLogServer and iocLogClient. The client code runs on each ioc and listens for the messages generated by the errlog system. It also reports the messages from vxWorks logMsg.

iocLogServer

This runs on a host. It receives messages for all enabled iocLogClients in the local area network. The messages are written to a file. Epics base provides a startup file "base/src/util/rc2.logServer", which is a shell script to start the server. Consult this script for details.

iocLogClient

This runs on each ioc. It is started by default when iocInit runs. The global variable iocLogDisable can be used to enable/disable the messages from being sent to the server. Setting this variable to (0,1) (enables,disables) the messages generation. If iocLogDisable is set to 1 immediately after iocCore is loaded then iocLogClient will not even initialize itself.

RETURN TO SLAC CMLOG HOME PAGE

SLAC Last modified: 12-Aug- 2000 by Ron MacKenzie