unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

MSG_SEND(3L)                                                      MSG_SEND(3L)



NAME
       msg_send,  msg_recv, msg_reply, MSG_RECVALL, msg_enumsend, msg_enumrecv
       - LWP send and receive messages

SYNOPSIS
       #include <&lt;lwp/lwp.h>&gt;

       int msg_send(dest, arg, argsize, res, ressize)
       thread_t dest; /* destination thread */
       caddr_t arg;   /* argument buffer */
       int argsize;   /* size of argument buffer */
       caddr_t res;   /* result buffer */
       int ressize;   /* size of result buffer */

       int msg_recv(sender, arg, argsize, res, ressize, timeout)
       thread_t *sender;   /* value-result: sending thread or agent */
       caddr_t *arg;       /* argument buffer */
       int *argsize;       /* argument size */
       caddr_t *res;       /* result buffer */
       int *ressize;       /* result size */
       struct timeval *timeout; /* POLL, INFINITY, else timeout */

       int msg_reply(sender)
       thread_t sender;    /* agent id or thread id */

       int msg_enumsend(vec, maxsize)
       thread_t vec[];     /* list of blocked senders */
       int maxsize;

       int msg_enumrecv(vec, maxsize)
       thread_t vec[];     /* list of blocked receivers */
       int maxsize;

       int MSG_RECVALL(sender, arg, argsize, res, ressize, timeout)
       thread_t *sender;
       caddr_t *arg;
       int *argsize;
       caddr_t *res;
       int *ressize;
       struct timeval *timeout;

DESCRIPTION
       Each thread queues messages addressed to it as  they  arrive.   Threads
       may either specify that a particular sender's message is to be received
       next, or that any sender's message may be received next.

       msg_send() specifies a message buffer and a reply buffer, and initiates
       one  half  of  a  rendezvous  with the receiver.  The sender will block
       until the receiver replies using msg_reply().  msg_recv() initiates the
       other  half of a rendezvous and blocks the invoking thread until a cor-
       responding msg_send() is received.  When unblocked by  msg_send(),  the
       receiver  may  read  the message and generate a reply by filling in the
       reply buffer and issuing msg_reply().  msg_reply() unblocks the sender.
       Once  a  reply is sent, the receiver should no longer access either the
       message or reply buffer.

       In msg_send(), argsize specifies the size in bytes of the argument buf-
       fer  argbuf, which is intended to be a read-only (to the receiver) buf-
       fer.  ressize specifies the size in bytes of the result buffer  resbuf,
       which is intended to be a write-only (to the receiver) buffer.  dest is
       the thread that is the target of the send.

       msg_recv() blocks the receiver until:

       o  A message from the agent or thread bound to sender has been sent  to
          the receiver or,

       o  sender  points  to  a THREADNULL-valued variable and any message has
          been sent to the receiver from a thread or agent, or,

       o  After the time specified  by  timeout  elapses  and  no  message  is
          received.

       If  timeout  is POLL, msg_recv() returns immediately, returning success
       if the message expected has arrived; otherwise an  error  is  returned.
       If timeout is INFINITY, msg_recv() blocks forever or until the expected
       message arrives.  If timeout is any other value msg_recv()  blocks  for
       the  time  specified  by timeout or until the expected message arrives,
       whichever comes first.  When msg_recv() returns, sender  is  filled  in
       with  the  identity  of  the  sending  thread  or agent, and the buffer
       addresses and sizes specified by the matching send are stored  in  arg,
       argsize, res, and ressize.

       msg_enumsend()  and  msg_enumrecv() are used to list all of the threads
       blocked on sends (awaiting a reply) and  receives  (awaiting  a  send),
       respectively.   The  value  returned  is  the  number  of  such blocked
       threads.  The vector supplied by the client is filled  in  (subject  to
       the  maxsize limitation) with the ID's of the blocked threads.  maxsize
       is used to avoid exceeding the capacity of the list.  If the number  of
       threads blocked on sends or receives is greater than maxsize, only max-
       size thread ID's are filled in vec.  If maxsize is 0,  just  the  total
       number of blocked threads is returned.

       sender  in msg_recv() is a reference parameter.  If you wish to receive
       from any sender, be sure to reinitialize the thread sender points to as
       THREADNULL  before  each  use (do not use the address of THREADNULL for
       the sender).  Alternatively, use the MSG_RECVALL() macro.   This  macro
       has  the  same parameters as msg_recv(), but ensures that the sender is
       properly initialized to allow receipt from any  sender.   MSG_RECVALL()
       returns the result from msg_recv.

RETURN VALUES
       msg_send(), msg_recv(), MSG_RECVALL() and msg_reply() return:

       0      on success.

       -1     on failure.

       msg_enumsend() returns the number of threads blocked on msg_send().

       msg_enumrecv() returns the number of threads blocked on msg_recv().

ERRORS
       msg_recv() will fail if one or more of the following is true:

       LE_INVALIDARG       An illegal timeout was specified.

                           The sender address is that of THREADNULL.

       LE_NONEXIST         The specified thread or agent does not exist.

       LE_TIMEOUT          Timed out before message arrived.

       msg_reply() will fail if one or more of the following is true:

       LE_NONEXIST         Attempt to reply to a sender that does not exist or
                           has terminated.

       LE_NOWAIT           Attempt to reply to a sender that is not  expecting
                           a reply.

       msg_send() will fail if one or more of the following is true:

       LE_INVALIDARG       Attempt to send a message to yourself.

       LE_NONEXIST         The  specified destination thread does not exist or
                           has terminated.



                                21 January 1990                   MSG_SEND(3L)