\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{rciSend}{3}
\manSection{NAME}
{\tt \manName{rciSend}}, 
{\tt \manName{rciReceive}}, 
{\tt \manName{rciFlush}}
 -- RCI message passing primitives.
\manSection{USAGE}
\cverbatim
rciSend (taskMask, buffer, size)
   unsigned long taskMask;
   const char *buffer;
   int size;

rciReceive (taskMask, buffer, size, sender)
   unsigned long taskMask;
   char *buffer;
   int size;
   RCI_DESC **sender; 

rciFlush (taskMask)
   unsigned long taskMask; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt taskMask} --} 
Bitmask describing tasks to which messages are to be sent, or
from which they are to be received.
\manItem{{\tt buffer} --}
Buffer containing the message to be sent, or into which it is to be received.
\manItem{{\tt size} --}
Numbers of bytes to be sent, or maximum number of bytes to be received.
\manItem{{\tt sender} --}
(Optional) pointer through which is returned the task descriptor
of the task which sent the received message.
\manSection{DESCRIPTION}
These routines may be called from any part of an RCI program.

{\tt rciSend()} sends a message of {\tt size} bytes contained in
{\tt buffer} to the task described by {\tt taskMask}. Only one target
may (presently) be specified. The task code for a particular task may
be found from the task descriptor with the macro {\tt TASKMASK(td)}.
The function returns the number of bytes sent (which will equal {\tt size}
unless there was an error).
The largest message that can be sent is defined by {\tt MAX_MSG}. The
size of the pool used to allocate message buffer space is {\tt MSG_POOL_SIZE}.
All messages use a minimum internal buffer size defined by {\tt MIN_MSG}.

{\tt rciReceive()} receives a message into {\tt buffer}, which is
truncated to {\tt size}, if necessary. The message is received from
any sending task described by {\tt taskMask}. Non-existent
task specifications are ignored, so {\tt (unsigned long)\~0} may be used
to request a message from any task. The function returns
the number of bytes received, or {\tt 0} if there are no messages.

{\tt rciFlush()} flushes all incoming messages sent by the tasks specified
in the argument {\tt taskMask}. Again, 
{\tt (unsigned long)\~0} may be used to denote all tasks.

\manSection{DIAGNOSTICS}

{\tt rciSend()} returns {\tt -1} in the event of an error, and places one of
the following codes on the {\it errorStack} (q.v.):

\manItem{{\tt ETooMany} --}
The sending task currently has more
then {\tt MAX_OUT\-STAND\-ING_\-MSGS} outstanding (i.e., sent but not yet read
by the target tasks), or the input queue for the target task itself is full.
\manItem{{\tt EMemory} --}
Insufficient memory to buffer the message itself.
\manItem{{\tt EDescriptor} --}
The mask describing the target task is invalid (if this mask is 0,
then {\tt rciSend()} will return {\tt 0} instead of an error).

Errors detected by other functions are internal, and
when detected will result in a program abort.

\manSection{SEE ALSO}
\raggedright
{\tt rciCreate(3)}.
\manEnd
\end
