asyncmsg_get()

Receive an asynchronous message

Asynchronous messaging is an experimental feature; for information about the use of experimental software, see the Commercial Software License Agreement (CSLA) or Partner Software License Agreement (PSLA) in the Licensing area of our website, http://www.qnx.com/legal/licensing/.

Synopsis:

#include <sys/asyncmsg.h>

struct _asyncmsg_get_header *asyncmsg_get( int chid );

Arguments:

chid: The channel ID.

Library:

libasyncmsg

Use the -l asyncmsg option to qcc to link against this library.

Description:

The asyncmsg_get() function receives up to five asynchronous messages from the channel identified by the chid argument. In order to receive more messages, you must call this function in a loop until the function returns NULL and sets errno to EAGAIN to signify that you've drained the queue of messages.

Threads that receive asynchronous messages don't inherit the sender's priority.

If you provided a callback function when you called asyncmsg_channel_create(), asyncmsg_get() invokes the callback to allocate space for the message; otherwise asyncmsg_get() invokes malloc().

`_asyncmsg_get_header` structure

The asyncmsg_get() function stores each asynchronous message in an _asyncmsg_get_header structure:

struct _asyncmsg_get_header {
    struct _msg_info info;
    int err;
    iov_t *iov;
    int parts;
    struct _asyncmsg_get_header *next;
    unsigned reserve[2];
};

The members include:

info: A _msg_info structure, just as for synchronous messages.
err: The error status of this message.
iov: A pointer to the IOV (Input/Output Vector) for the message body.
parts: The size of the iov array.
next: A pointer to the next message returned by asyncmsg_get().

Returns:

A pointer to a linked list of _asyncmsg_get_header structures containing the messages received, or NULL if an error occurred (errno is set).

You should free this list of headers when you're finished with them.

Errors:

EBADF: The channel specified by chid doesn't exist.
EFAULT: A fault occurred when the kernel tried to access the buffers provided.
EMSGSIZE: The buffer provided isn't big enough to hold the received message.
EAGAIN: No message is available at this time.

Classification:

QNX Neutrino

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