MsgWritev(), MsgWritev_r()

Write a reply

Synopsis:

#include <sys/neutrino.h>

int MsgWritev( int rcvid,
               const iov_t* iov,
               int parts,
               int offset );

int MsgWritev_r( int rcvid,
                 const iov_t* iov,
                 int parts,
                 int offset );

Library:

libc

Description:

The MsgWritev() and MsgWritev_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 data is read from the array of buffers pointed to by iov. The number of elements in the array is given by parts. The offset allows you to write data to the sender's reply message starting at any point. The data transfer occurs immediately and your thread doesn't block. The state of the sending thread doesn't change.

If you attempt to write past the end of the sender's reply message then MsgWritev() 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, MsgWritev() 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 MsgWritev() 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 MsgWritev() followed by a call to MsgReply*().

Blocking states

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

Returns:

The only difference between the MsgWritev() and MsgWritev_r() functions is the way they indicate errors:

MsgWritev()

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

MsgWritev_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(), MsgWrite()