resmgr_msggetv()

Updated: April 19, 2023

Read a message from a client, from local data, or both

Synopsis:

#include <sys/resmgr.h>

ssize_t resmgr_msggetv( resmgr_context_t * const ctp,
                        iov_t * const *rmsg,
                        const size_t rparts,
                        size_t offset );

Arguments:

ctp
A pointer to a resmgr_context_t structure that the resource manager library uses to pass context information between functions. This function extracts the rcvid and other message-related parameters from this structure.
rmsg
An array of buffers where the function can store the data. The function can modify the individual iov_base and iov_len members of iov_t structures, but restores them to their original data before it returns.
rparts
The number of elements in the array specified by rmsg.
offset
An offset into the current message that indicates where you want to start reading the data. The value of offset that ctp references cannot be included in this parameter.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The resmgr_msggetv() function is a convenience function that you can use in a resource manager instead of resmgr_msgreadv() or MsgReadv().

Based on the requested data offset, the function first copies data from the current local message buffer (if applicable) and then gets the rest of the data (if applicable) from the client by calling MsgRead().

Because combine message offsets are automatically handled, the caller does not add the offset that ctp references to the passed in offset. The passed in offset is just the offset from the start of the current message being processed.

For combine messages (those with the _IO_COMBINE_FLAG set), the amount of data returned to the caller is limited to the size found in the size parameter that ctp references. This limit ensures that the caller does not get data from a subsequent message by mistake.

For more information, see Layers in a resource manager in the Bones of a Resource Manager chapter of Writing a Resource Manager.

Returns:

The number of bytes read, or -1 if an error occurs (errno is set).

Errors:

EDEADLK
A deadlock occurred. You can avoid a deadlock by setting the _NTO_CHF_MSG_PAUSING flag when you create a channel; for more information, see ChannelCreate() and MsgPause().
EFAULT
A fault occurred in a server's address space when the kernel tried to access the server's message buffers.
EOVERFLOW
The sum of the IOV lengths exceeds SSIZE_MAX, or the number of parts exceeds 524288.
ESRCH
The thread indicated by ctp->rcvid doesn't exist, is no longer REPLY-blocked on the channel, or the connection was detached.
ESRVRFAULT
A fault occurred when the kernel tried to access the buffers provided.
ETIMEDOUT
A kernel timeout unblocked the call. See TimerTimeout().

Classification:

QNX Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes