errorStack(3)

NAME
errorMsg, getErrorMsg, getErrorCode, setErrorCode, numErrors, popError, clearErrors, printErrors -- Error stack management routines.

USAGE
errorMsg(code, format [arg,] ...)
   int code;
   char *format;

char *getErrorMsg(level)
   int level;

getErrorCode(level)
   int level;

setErrorCode(level, code)
   int level;
   int code;

numErrors()

popError()

clearErrors()

dumpErrorMsgs(buf, size)
   char *buf;
   int size;

printErrors()

ARGUMENTS

code --
    Error code.

format --
    printf style format string.

level --
    Indicates a level on the error stack, with 0 denoting the most recently added information.

buf --
    Buffer for receiving error messages.

size --
    Size of the buffer, in bytes.

RESTRICTIONS
printErrors() must be called from the planning level.

DESCRIPTION
The errorStack is a mechanism for producing a chain of error codes and messages. A routine which encounters an error can record an error code and an associated message with the routine errorMsg(); these are then placed on the error stack. Higher level routines can then add their own error code and message to the stack, and so on. The contents of the error stack provides a record of successive error events, which is particularly useful in fault diagnosis.

errorMsg() pushes an error code and message onto the stack. The message is described using the standard printf style format. A variable number of arguments may follow the format string. A newline character is not added to the message; this must be explicitly placed in the format string if desired. errorMsg() returns 1 if successful or 0 if the stack is full.

getErrorMsg() returns the error message located at a particular stack level or NULL if the level is undefined.

setErrorCode() sets the error code located at a particular stack level, returning 1 if successful or 0 if the level is undefined.

getErrorCode() returns the error code located at a particular stack level and 0 if the level is undefined.

clearErrors() clears the error stack.

popError() removes an error code and message from the error stack, returning 1 if successful or 0 if the stack is empty.

numErrors() returns the number of errors currently on the stack.

dumpErrorMsgs() prints all of the messages on the error stack into the buffer given by buf and size, truncating if necessary. It does not clear the stack.

printErrors() prints all of the messages on the error stack to stdout, starting with the most recently added. It does not clear the stack. If a stack overflow occurred since the last time the stack was cleared, a diagnostic is printed indicating this.

INTERACTION WITH RCI TASKS
Each RCI task has its own error stack, which is maintained with the context of the task. Thus calling errorMsg() from the planning level and from an RCI task will cause the message to go to two separate places.

To access the error stack for an RCI task without having to be in that task's context, one can use the routines described in rciErrorStack(3).

SEE ALSO
rciErrorStack(3), rciAbortErrors(3).

"Standard" RCI error codes are defined in the file <errorCodes.h>.