\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{rciAbortHandler}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{rciAbortHandler}}
-- RCI routine to set up an abort handler.
}
\manSection{USAGE}
\cverbatim
int (*rciAbortHandler(fxn))()
   int (*fxn)(); @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt fxn} --}
Handling function.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{DESCRIPTION}
When an RCI abort is issued (as a result of some part of the
system or user software calling {\tt rciAbort()}),
the default action taken by the system
is to print the error message and code associated with the abort
condition and exit. It is possible, however, for the planning task
to catch the abort and take its own action (unless the abort
code specified by {\tt rciAbort()} is {\TT EInternal} or {\TT EFatal} 
(see below)).   

{\tt rciAbortHandler()}
specifies a handler for an abort
condition, returning the previous handler, if any. 

When an abort occurs, all control tasks are released and
the planning task receives a {\tt SIGHUP} signal. This invokes
a first level handler that checks to make sure all of the control tasks
have acknowledged the abort and released, and then calls either the
default abort handler or one specified by the user. The default handler
prints out the message specified by {\tt rciAbort()} and forces a
program exit. A user specified abort handler may recover from the abort
by long jumping to another part of the program.

An abort handler is called with the
following three arguments:

\cverbatim
        abortHandler (code, msg, td)
          int code;
          char *msg;
          RCI_DESC *td;
@endcverbatim

{\TT code} and {\TT msg} are the error code and message specified in the {\tt
rciAbort()} call. {\TT td} is the task
descriptor of the task from which {\tt rciAbort()} was called. If {\tt
rciAbort()} was called internally by the system, then this task descriptor
is likely to be the one associated with the planning task. 

The arguments to the abort function provide descriptive information
about the abort condition. An abort handler which emulates the default
abort handler looks something like this:

\cverbatim
   abortHandler (code, msg, td)
   int code;
   char *msg;
   RCI_DESC *td;
   {
        printf ("\nRCI ABORT: task '%s' on cpu %d\n%s\n", 
                rciTaskName(td), td->cpu, msg);
        exit (-1);
   }
@endcverbatim

\manSection{DIAGNOSTICS}
The routine will abort the program if called from the control level.
\manSection{NOTES}
An RCI abort will result in a program exit, regardless of whether the
user has set up an abort handler, if the abort code is
either {\TT EInternal} or {\TT EFatal} 
(defined in {\filefont h/errorCodes.h}). 
These abort codes are used to indicate either an internal software
error or some other condition that is necessarily fatal to the program.
\manSection{SEE ALSO}
\raggedright
{\tt rciAbort(3)}.
\manEnd
\end
