Receivemx()

check for a message from another process

Synopsis:

#include <sys/kernel.h>
#include <sys/sendmx.h>
pid_t Receivemx( pid_t pid,
                 unsigned parts,
                 struct _mxfer_entry *msgmx );

Description:

The kernel function Receivemx() checks to see if a message is waiting 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 array of message buffers pointed to by msgmx. The number of elements in this array is given by nparts, which must not exceed _QNX_MXTAB_LEN (defined in <limits.h>). The size of the received message is limited to the total size of these buffers. 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 send to this 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 are RECEIVE BLOCKED on it, Receivemx() returns -1 and errno is set to ESRCH.

Receivemx() 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.

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

It's quite common to receive a 2-part message consisting of a fixed header and a buffer of data. The sender need not specify the same number or size of buffers. The data is laid down, filling each entry as required.

Avoid stuffing each _mxfer_entry directly. Instead, use the _setmx() macro to stuff each entry. This will make your code portable across 16- and 32-bit platforms.

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 Sendmx().

Classification:

QNX

Caveats:

Receivemx() is a macro.

See also:

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