Readmsgmx()

read a message from another process

Synopsis:

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

Description:

The kernel function Readmsgmx() reads data into an array of buffers pointed to by msgmx from the process identified by pid. The number of elements in the array, parts, must not exceed _QNX_MXTAB_LEN (defined in <limits.h>). The offset allows you to read data from the sender's send message starting at any point. The data transfer occurs immediately, and your task doesn't block. The state of the process pid isn't changed.

The process pid must have sent a message that was received and not yet replied to. It must be in the REPLY BLOCKED state.

If you attempt to read past the end of the sender's message then Readmsgmx() returns fewer bytes than was specified in the sum of the buffer lengths in the _mxfer_entry list provided.

This function is often used in one of three situations:

1. You may receive a message consisting of a fixed header and a variable amount of data. The header contains the byte count of the data. If the data is large and has to be inserted into one or more buffers (like a file system cache), rather than read the data into one large buffer and then copy it into several other buffers, you can read only the header, then build an _mxfer_entry list to read the data directly into the required buffers.
2. You receive a message that you can't process now. At some point in the future, an event will occur that will allow you to process it. Rather than save the entire message in your space, you may elect only to save the process id, and re-read the message when the event occurs. You can't reply to the process until you have read its message.
3. You receive messages that are larger than your buffer space. Perhaps you're an agent in the middle of two processes, and simply filter the data and pass it on. You can use Readmsg() to read the message in small gulps. You might also want to look at Writemsg() for writing messages in small gulps.

When you're through using Readmsgmx(), you must use Reply() or Replymx() to ready the REPLY BLOCKED process and complete the message exchange. 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 number of bytes read. On error, -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

Call interrupted by a signal.

ESRCH

The process pid doesn't exist.

Examples:

See Sendmx().

Classification:

QNX

Caveats:

Readmsgmx() is a macro.

See also:

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