MsgReceive(), MsgReceive_r()
Wait for a message or pulse on a channel
Synopsis:
#include <sys/neutrino.h> int MsgReceive( int chid, void * msg, int bytes, struct _msg_info * info ); int MsgReceive_r( int chid, void * msg, int bytes, struct _msg_info * info );
Arguments:
- chid
- The ID of a channel that you established by calling ChannelCreate() .
- msg
- A pointer to a buffer where the function can store the received data.
- bytes
- The size of the buffer.
- info
- NULL, or a pointer to a _msg_info structure where the function can store additional information about the message.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
The MsgReceive() and MsgReceive_r() kernel calls wait for a message or pulse to arrive on the channel identified by chid, and store the received data in the buffer pointed to by msg.
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 message is waiting on the channel when you call MsgReceive(), the calling thread doesn'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 you pass a non-NULL pointer for info, the functions store additional information about the message and the thread that sent it in the _msg_info structure that info points to. You can get this information later by calling MsgInfo() .
On sucess, MsgReceive() and MsgReceive_r() return:
- >0
- A message was received; the returned value is a a rcvid (receive identifier). You'll use the rcvid with other Msg*() kernel calls to interact with and reply to the sending thread. MsgReceive() changes the state of the sending thread to REPLY-blocked when the message is received. When you use MsgReply*() to reply to the received message, 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; msg contains a pulse message of type _pulse . When a pulse is received, the kernel space allocated to hold it is immediately released. The _msg_info structure isn't updated.
Blocking states
State | Meaning |
---|---|
STATE_RECEIVE | There's no message waiting |
Returns:
The only difference between MsgReceive() and MsgReceive_r() is the way they indicate errors. On success, both functions return a positive rcvid if they received a message, or 0 if they received a pulse.
If an error occurs:
- MsgReceive() returns -1 and sets errno .
- MsgReceive_r() returns the negative of a value from the Errors section is returned. 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 MsgReceive() 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 MsgReceive() 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 |
Caveats:
The maximum size for a one-part message-pass is 231 − 1 (SSIZE_MAX).