NAME
msg_receive - retrieves next message from port queue

SYNOPSIS
#include <sys/message.h>
#include <sys/port.h>

msg_return_t msg_receive(header, option, timeout)
msg_header_t *header; /* in/out */
msg_option_t option;
msg_timeout_t timeout;

ARGUMENTS
header The address of a buffer in which the message is
to be received. Two fields of the message
header must be set before the call is made:
msg_local_port is set to the name of the port
or port set from which the message is to be
received and msg_size must be set to the
maximum size of the message that may be
received. It must be less than or equal to the
size of the buffer.

timeout If RCV_TIMEOUT is specified this value is the
maximum time in milliseconds to wait for a
message before giving up.

option The failure conditions under which msg_receive
should terminate; the value of this parameter
is a bit or’d combination the following two
options. Unless one of the two following
values for the option parameter is explicitly
specified, msg_receive does not return until a
message has been received.

RCV_TIMEOUT Specifies that msg_receive should return when
the specified timeout elapses, if a message has
not arrived by that time; if not specified, the
timeout will be ignored (i.e. infinite).

RCV_NO_SENDERS Specifies that msg_receive should return if the
receiver and owner tasks have the only access
rights to the port specified in the message
header. (Not implemented yet)

RCV_INTERRUPT Specifies that msg_receive should return when a
software interrupt has occurred in this thread.

MSG_OPTION_NONE Specifies that none of the above options are
desired.

DESCRIPTION
msg_receive retrieves the next message from a port or port set
specified in the msg_local_port field of the specified message
header. If a port is specified, the port may not be a member of a
port set. The msg_local_port field will be set to the specific
port on which the message was found.

If a port set is specified, the msg_receive will retrieve messages
sent to any of the set’s member ports. It is not an error for the
port set to have no members, or for members to be added and removed
from a port set while a msg_receive on the port set is in progress.

The message consists of its header, followed by a variable amount
of data; the message header supplied to msg_receive must specify
the maximum size of the message which can be received into the
buffer provided.

If no messages are present on the port(s) in question, msg_receive
will wait until a message arrives, or until one of the specified
termination conditions is met (see above for discussion of the
option parameter).

If the received messages contains out-of-line data (i.e. for which
the msg_type_inline attribute was specified as FALSE), the data
will be returned in a newly-allocated region of memory; the message
body will contain a pointer to that new region. (See vm_allocate
call for a description of the state of newly-allocated memory.) The
user may wish to deallocate this memory when the data is no longer
needed.

DIAGNOSTICS
RCV_SUCCESS The message has been received.

RCV_INVALID_MEMORY The message specified was not writable by
the calling task.

RCV_INVALID_PORT An attempt was made to receive on a port
to which the calling task does not have
the proper access, or which was
deallocated (see port_deallocate) while
waiting for a message.

RCV_TOO_LARGE The message header and body combined are
larger than the size specified by
msg_size.

RCV_NOT_ENOUGH_MEMORY The message to be received contains more
out-of-line data than can be allocated in
the receiving task.

RCV_TIMED_OUT The message was not received after timeout
milliseconds.

RCV_ONLY_SENDER An attempt was made to receive on a port
to which only the receive and/or owner
have access, and the RCV_NO_SENDERS option
was specified.

RCV_INTERRUPTED A software interrupt occurred.

RCV_PORT_CHANGE The port specified was moved into a port
set during the duration of the msg_receive
call.