\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{rciAbort}{3}
\manSection{NAME}
{\tt \manName{rciAbort}},
{\tt \manName{rciAbortErrors}}
-- abort an RCI control session.
\manSection{USAGE}
\cverbatim
rciAbort(code, format, [arg1] ... [,argn])
   int code;
   char *format; 

rciAbortErrors() @endcverbatim

\manSection{ARGUMENTS}
\manItem{{\tt code} --}
Error code.
\manItem{{\tt format} --}
{\tt printf()} style format string.
\manItem{{\tt args} --}
Values to be printed in the message.
\manSection{DESCRIPTION}
{\tt rciAbort()} is a routine that may be called from any
part of an RCI program to cause an RCI abort. 
Upon an abort condition, all tasks are
released, and an abort handler (bound the to signal {\tt SIGHUP}) is called
in the planning task. An abort is associated with an integer code and a
message, which are passed as arguments to the abort handler along with
information about which control task and CPU originated the abort. The maximum
size of the message produced should not exceed {\tt EMSG_MAX}
(defined in {\filefont h/errlog.h}).

Once an abort condition has been asserted, 
subsequent calls to {\tt rciAbort()}
are ignored until all tasks are released.

{\tt rciAbortErrors()} is similar to {\tt rciAbort()}, except that
instead of taking code and message arguments, it uses the current
contents of the task's error stack (see {\tt errorStack(3)}). 
The code is taken to be the most recently placed error code,
and the message is taken to be the current list of error messages.

The abort routine works by setting abort flags in the control blocks
of all the active tasks, and then sending a {\tt SIGHUP} signal to the
planning task. The system catches the signal and then waits for all active
tasks to acknowledge the abort and release themselves before
calling the abort handler. If this does not happen in a reasonable length of
time, a fatal condition is raised and the program exits. 

The default abort handler simply prints out task information
and the abort message, 
and calls {\tt exit(2)}. The programmer can set up
his/her own abort handler with the call {\tt rciAbortHandler()} (q.v.).

\manSection{DIAGNOSTICS}
{\tt rciAbort()} returns {\tt 1} normally, or {\tt 0} if an abort condition has 
already been asserted.

\manSection{SEE ALSO}
{\tt errorStack(3)}, {\tt rciAbortHandler(3)}.

``Standard'' error codes for {\tt rciAbort()} are defined
in {\filefont h/errorCodes.h}.
\manEnd
