MsgWrite(), MsgWrite_r()

Write a reply

Synopsis:

#include <sys/neutrino.h>

int MsgWrite( int rcvid,
              const void* msg, 
              int size,
              int offset );

int MsgWrite_r( int rcvid,
                const void* msg, 
                int size,
                int offset );

Library:

libc

Description:

The MsgWrite() and MsgWrite_r() functions are identical except in the way they indicate errors. See the Returns section for details.

These kernel calls write data to the reply buffer of a thread identified by rcvid. The rcvid is returned from MsgReceive*() when you receive the message. The thread being written to must be in the REPLY-blocked state. Any thread in the receiving process is free to write to the reply message.

The size bytes of data is read from the buffer pointed to by msg, and written to the sender's buffer starting at the specified offset.

If you attempt to write past the end of the sender's reply message then MsgWrite() returns fewer bytes than requested. This function is used in one of two situations:

1. The data arrives over time and is quite large. Rather than buffer all the data, MsgWrite() can be used to write it into the destination thread's reply message buffer as it arrives.
2. Messages are received which are larger than available buffer space. Perhaps the process is an agent between two processes and simply filters the data and passes it on. MsgRead*() can be used to read messages in small amounts and MsgWrite() can be used to write messages in small amounts.

To complete a message exchange, MsgReply*() must be called. The reply doesn't need to contain any data. If it does contain data, then it will always be written at offset zero in the destination thread's reply message buffer. This is a convenient way of writing the header once all of the information has been gathered.

A single call to MsgReply*() is always more efficient than calls to MsgWrite() followed by a call to MsgReply*().

Blocking states

None. In the network case, lower priority threads may run.

Native networking

The MsgWrite() function has increased latency when it's used to communicate across a network -- the server is now writing data to its local npm-qnet, which may need to communicate with the client's npm-qnet to actually transfer the data. The server's MsgWrite() call effectively sends a message to the server's npm-qnet to initiate this data transfer.

But since the server's npm-qnet has no way to determine the size of the client's receive data area, the number of bytes reported as having been transferred by the server during its MsgWrite() may not be accurate -- the reported number will instead reflect the number of bytes transferred by the server to its npm-qnet.

Returns:

The only difference between the MsgWrite() and MsgWrite_r() functions is the way they indicate errors:

MsgWrite()

The number of bytes written. If an error occurs, -1 is returned and errno is set.

MsgWrite_r()

The number of bytes written. This function does NOT set errno. If an error occurs, the negative of a value from the Errors section is returned.

Errors:

EFAULT

A fault occurred in the sender's address space when a server tried to access the sender's return message buffer.

ESRCH

The thread indicated by rcvid doesn't exist or its connection was detached.

ESRVRFAULT

A fault occurred when the kernel tried to access the buffers provided.

Classification:

QNX 6

See also:

MsgRead(), MsgReadv(), MsgReceive(), MsgReceivev(), MsgReply(), MsgReplyv(), MsgWritev()