Receive()

wait for a message from a process

Synopsis:

#include <sys/kernel.h>
pid_t Receive( pid_t pid, void *msg,
               unsigned nbytes );

The kernel function Receive() waits for a message from the process identified by pid. If pid is nonzero, only messages from pid are received. If pid is zero, a message from any process or proxy is received. If a suitable message is waiting, it's received into the message buffer pointed to by msg, and is limited to a maximum size of nbytes. If a suitable message isn't waiting, your process blocks, and enters the RECEIVE BLOCKED state. It's made ready to run when an acceptable process sends it a message.

By default, messages sent to your process are queued in time order. This may be changed to priority order using the qnx_pflags() function.

If you pass a specific pid() (nonzero) and that process doesn't exist, or it dies while you're RECEIVE BLOCKED on it, Receive() returns -1 and errno is set to ESRCH.

Receive() may be interrupted by a signal, in which case it returns -1, and errno is set to EINTR.

The number of bytes transferred is the minimum of that specified by both the sender and the receiver. The send data never overflows the buffer area provided by the receiver.

Receive() changes the state of the sending task from SEND BLOCKED to REPLY BLOCKED when the message is received.

Receive() is a simple cover function that builds a single part _mxfer_entry on the stack and calls Receivemx(), which is the real kernel function. It's provided for convenience, since it's easier to use than Receivemx() for simple messages.

Returns:

The process ID of the process that sent the message that was received. This ID is needed to reply to the message. If an error occurs, -1 is returned, and errno is set.

Errors:

EFAULT: In order to complete the message exchange the current process would have incurred a segment violation. You need to make your buffer(s) larger, or limit the number of bytes allowed in the transfer.
EINTR: The call was interrupted by a signal.
ESRCH: The process pid doesn't exist.

Examples:

See Send().

Classification:

QNX

Safety:
Interrupt handler	No
Signal handler	Yes, but modifies errno
Thread	Yes

Caveats:

Receive() is a macro.