./_Man_SunOS_4.1.3_html/html3/msg

Manual page for MSG_SEND(3L)

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

SYNOPSIS

#include <lwp/lwp.h>

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 corresponding 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 buffer argbuf, which is intended to be a read-only (to the receiver) buffer. 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:

A message from the agent or thread bound to sender has been sent to the receiver or,
sender points to a THREADNULL-valued variable and any message has been sent to the receiver from a thread or agent, or,
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 maxsize 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.