NAME
mq_receive — receive a message from a message queue
SYNOPSIS
#include <sys/mqueue.h>
ssize_t mq_receive(mqd_t mqdes,
char *msg_ptr,
size_t msg_len,
unsigned int *msg_prio
);
DESCRIPTION
The
mq_receive()
system call receives the oldest of the highest priority message from the
message queue specified by
mqdes.
The selected message is removed from the queue and copied to the buffer
pointed to by the
msg_ptr
argument. The argument,
msg_len,
specifies the size of the buffer in bytes. The value of
msg_len
should be greater than or equal to the
mq_msgsize
attribute of the message queue, or
mq_receive()
will fail.
If the argument
msg_prio
is not
NULL,
the priority of the message removed from the queue is stored in the location
pointed to by
msg_prio.
If the specified message queue is empty and the
O_NONBLOCK
flag is not set
in the message queue blocking status associated with
mqdes,
mq_receive()
will block in priority order, until it can receive a message from the queue,
or until
mq_receive()
is interrupted by a signal. If the specified message queue is empty and the
O_NONBLOCK
flag is set in the message queue blocking status associated with
mqdes,
mq_receive()
will not wait for a message to arrive on the queue and will return with an
error.
To use this function, link in the realtime library by specifying
-lrt
on the compiler or linker command line.
RETURN VALUE
mq_receive()
returns the following values:
- n
Successful completion.
n
is the size of the selected message in bytes and the message is removed from
the queue.
- -1
Failure.
errno
is set to indicate the error and no message is removed from the queue.
ERRORS
If
mq_receive()
fails,
errno
is set to one of the following values:
- [EAGAIN]
The
O_NONBLOCK
flag is set in the message queue blocking status associated with
mqdes,
and the message queue is empty.
- [EBADF]
mqdes
is not a valid message queue descriptor open for reading.
- [EINTR]
A signal interrupted the call to
mq_receive().
- [EINVAL]
msg_ptr
points to an invalid address.
- [EMSGSIZE]
The specified message buffer size,
msg_len,
is less than the message size attribute of the message queue.
- [ENOSYS]
mq_receive()
is not supported by the implementation.
STANDARDS CONFORMANCE
mq_receive(): POSIX 1003.1b
Printable version
