\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{errorStack}{3}
\manSection{NAME}
{\tt \manName{errorMsg}}, 
{\tt \manName{getErrorMsg}}, 
{\tt \manName{getErrorCode}}, 
{\tt \manName{setErrorCode}},
{\tt \manName{numErrors}}, 
{\tt \manName{popError}}, 
{\tt \manName{clearErrors}}, 
{\tt \manName{printErrors}} --
Error stack management routines.
\manSection{USAGE}
\cverbatim
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() @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt code} --}
Error code.
\manItem{{\tt format} --}
{\tt printf} style format string.
\manItem{{\tt level} --}
Indicates a level on the error stack, with {\tt 0} denoting the most recently
added information.
\manItem{{\tt buf} --}
Buffer for receiving error messages.
\manItem{{\tt size} --}
Size of the buffer, in bytes.
\manSection{RESTRICTIONS}
{\tt printErrors()} must be called from the planning level.

\manSection{DESCRIPTION}
The {\it 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 {\tt 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.

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

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

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

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

{\tt clearErrors()} clears the error stack.

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

{\tt numErrors()} returns the number of errors currently on the stack.

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

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

\manSection{INTERACTION WITH RCI TASKS}
Each RCI task has its own error stack, which is maintained with the
context of the task. Thus calling {\tt 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
{\tt rciErrorStack(3)}.
\manSection{SEE ALSO}
\raggedright
{\tt rciErrorStack(3)}, {\tt rciAbortErrors(3)}.

``Standard'' RCI error codes are defined in the file
{\tt <errorCodes.h>}.
\manEnd
