MsgReceivev(), MsgReceivev_r()

Wait for a message or pulse on a channel

Synopsis:

#include <sys/neutrino.h>

int MsgReceivev( int chid,
                 const iov_t * riov,
                 int rparts,
                 struct _msg_info * info );

int MsgReceivev_r( int chid,
                   const iov_t * riov,
                   int rparts,
                   struct _msg_info * info );

Description:

The MsgReceivev() and MsgReceivev_r() functions are identical except in the way they indicate errors. See the Returns section for details.

These kernel calls wait for a message or pulse to arrive on the channel identified by chid. The channel chid was established by calling ChannelCreate(). The receive data is placed in the array of buffers pointed to by riov. The number of elements in the array is given by rparts.

The number of bytes transferred is the minimum of that specified by both the sender and the receiver. The received data won't be allowed to overflow the receive buffer area provided.

The first buffer of the IOV (input/output vector) must be big enough to contain a pulse. If it isn't, -1 is returned and errno is set to EFAULT.

If a message is waiting on the channel when MsgReceivev() is called, the calling thread won't block and the message is immediately copied. If a message isn't waiting, the calling thread enters the RECEIVE-blocked state until a message arrives.

If multiple messages are sent to a channel without a thread waiting to receive them, the messages are queued in priority order.

If a non-NULL pointer is passed for info, additional information on the message and the thread that sent it is saved there. If info is NULL, this information can be obtained later by calling the MsgInfo() kernel call. The contents of the _msg_info structure are described there.

The MsgReceivev() function returns a value that's referred to as a rcvid (receive identifier). It can take on the following values:

Value	Description
-1	An error occurred.
>0	A message was received. The rcvid is used by other Msg()* kernel calls to interact with and reply to the sending thread. MsgReceivev() changes the state of the sending thread to REPLY-blocked when the message is received. When the received message is replied to using MsgReply(), the sending thread is made ready again. The rcvid* encodes the sending thread's ID and a local connection ID.
0	A pulse was received. Unlike a message, a pulse shouldn't be replied to using MsgReply()*. When a pulse is received, the kernel space allocated to hold it is immediately released. The `_msg_info` structure isn't updated.

When a pulse is received, the IOV's first buffer contains a pulse message of type struct _pulse, that contains at least the following members:

Member	Description
`uint16_t` type	0
`uint16_t` subtype	0
`int8_t` code	A pulse code. System pulses are defined in `<sys/neutrino.h>`
`union sigval` value	Information relevant to the code
`int32_t` scoid	Server connection ID

Blocking states

State	Meaning
STATE_RECEIVE	There's no message waiting.

Returns:

The only difference between the MsgReceivev() and MsgReceivev_r() functions is the way they indicate errors:

MsgReceivev(): A rcvid (receive ID). If an error occurs, -1 is returned and errno is set.
MsgReceivev_r(): A rcvid (receive ID). This function does NOT set errno. If an error occurs, the negative of a value from the Errors section is returned.

Errors:

EFAULT: A fault occurred when the kernel tried to access the buffers provided. Because QNX accesses the sender's buffers only when MsgReceivev() is called, a fault could occur in the sender if the sender's buffers are invalid. If a fault occurs when accessing the sender buffers (only) they'll receive an EFAULT and MsgReceivev() won't unblock.
EINTR: The call was interrupted by a signal.
ESRCH: The channel indicated by chid doesn't exist.
ETIMEDOUT: A kernel timeout unblocked the call. See TimerTimeout().

Classification:

QNX 6

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes