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 );

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

unsigned Readmsgmx( pid_t pid,
             unsigned offset, parts,
             struct _mxfer_entry __far *msgmx );

Description:

The kernel function Readmsgmx() reads data into an array of buffers pointed to by msgmx from the process identified by pid. 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 does not block. The state of the process pid is not 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 cannot 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 cannot reply to the process until you have read its message.
  3. You receive messages that are larger than your buffer space. Perhaps you are 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 are 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, a (-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.

See also:

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

Examples:

See Sendmx().

Classification:

QNX

Systems:

MACRO, QNX