Receive

wait for a message from a process

Synopsis:

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

/* Note: in the 16-bit libraries, the prototype
   is: */

pid_t Receive( pid_t pid, void __far *msg,
               unsigned nbytes );

Description:

The kernel function Receive() waits for a message from the process identified by pid. If pid is non-zero then only messages from pid are received. If pid is zero then a message from any process or proxy is received. If a suitable message is waiting, it is received into the message buffer pointed to by msg, and is limited to a maximum size of nbytes. If a suitable message is not waiting, your process blocks, and enters the RECEIVE BLOCKED state. It is made ready to run when a 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() (non-zero), and that process doesn't exist, or it dies while you are RECEIVE BLOCKED on it, then 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 is provided for convenience, since it is easier to use than Receivemx() for simple messages.

Returns:

The Receive() function 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 does not exist.

See also:

Creceive(), Creceivemx(), errno, Receivemx(), Reply(), Replymx(), Readmsg(), Readmsgmx(), Send(), Sendfd(), Sendfdmx(), Sendmx(), Writemsg(), Writemsgmx(), Trigger()

Examples:

See Send().

Classification:

QNX

Systems:

MACRO, QNX