MsgReceivePulsev(), MsgReceivePulsev_r()

Receive a pulse on a channel

Synopsis:

#include <sys/neutrino.h>

int MsgReceivePulsev( int chid,
                      const iov_t * piov,
                      int parts,
                      struct _msg_info * info );

int MsgReceivePulsev_r( int chid,
                        const iov_t * piov,
                        int parts,
                        struct _msg_info * info );

Description:

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

These kernel calls wait for a 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 piov. The number of elements in the array is given by parts.

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 pulse is waiting on the channel when MsgReceivePulsev() is called, the calling thread won't block and the pulse is immediately copied. If a pulse isn't waiting, the calling thread enters the RECEIVE-blocked state until a pulse arrives.

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

Since the info parameter isn't updated, you'll typically pass NULL.

The MsgReceivePulsev() 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 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.

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 pulse waiting.

Returns:

The only difference between the MsgReceivePulsev() and MsgReceivePulsev_r() functions is the way they indicate errors:

MsgReceivePulsev(): A rcvid (receive ID). If an error occurs, -1 is returned and errno is set.
MsgReceivePulsev_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 MsgReceivePulsev() 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 MsgReceivePulsev() 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