MsgReceivePulse(), MsgReceivePulse_r()
Receive a pulse on a channel
Synopsis:
#include <sys/neutrino.h> int MsgReceivePulse( int chid, void * pulse, int bytes, struct _msg_info * info ); int MsgReceivePulse_r( int chid, void * pulse, int bytes, struct _msg_info * info );
Arguments:
- chid
- The ID of a channel that you established by calling ChannelCreate() .
- pulse
- A pointer to a buffer where the function can store the received data.
- bytes
- The size of the buffer.
- info
- The function doesn't update this structure, so you typically pass NULL for this argument.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The MsgReceivePulse() and MsgReceivePulse_r() kernel calls wait for a pulse to arrive on the channel identified by chid and place the received data in the buffer pointed to by pulse.
These functions are identical, except in the way they indicate errors; see the Returns section for details.
The number of bytes transferred is the minimum of that specified by both the sender and the receiver. The received data isn't allowed to overflow the receive buffer area provided.
If a pulse is waiting on the channel when you call MsgReceivePulse(), the calling thread doesn'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.
On success, MsgReceivePulse() and MsgReceivePulse_r() return 0 to indicate that they received a pulse. When a pulse is received:
- the kernel space allocated to hold it is immediately released
- pulse contains a pulse message of type _pulse .
Blocking states
State | Meaning |
---|---|
STATE_RECEIVE | There's no pulse waiting. |
Returns:
The only difference between MsgReceivePulse() and MsgReceivePulse_r() is the way they indicate errors. On success, they both return 0.
If an error occurred:
- MsgReceivePulse() returns -1 and sets errno .
- MsgReceivePulse_r() returns the negative of a value from the Errors section. This function doesn't set errno.
Errors:
- EFAULT
- A fault occurred when the kernel tried to access the buffers provided. Because the OS accesses the sender's buffers only when MsgReceivePulse() 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 MsgReceivePulse() 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:
Safety: | |
---|---|
Cancellation point | No |
Interrupt handler | No |
Signal handler | Yes |
Thread | Yes |