Receive an asynchronous message
CAUTION:
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/.
Note:
Asynchronous messaging support is in its own kernel module.
In order to use it, you must add [module=async] to the procnto
line of your mkifs buildfile.
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.
Note:
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).
Note:
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 |