NAME

mq_receive − receive a message from a message queue

SYNOPSIS

#include <mqueue.h>
int mq_receive (mqdes, msg_ptr, msg_len, msg_prio);
mqd_t mqdes;
char ∗msg_ptr;
size_t msg_len;
unsigned int ∗msg_prio;

DESCRIPTION

The mq_receive() function is used to receive the highest priority message from the message queue specified by mqdes.  The selected message is removed from the message queue and copied to the buffer pointed to by the msg_ptr argument.  If the size of the buffer, which is specified by the msg_len argument, is less than the mq_msgsize attribute of the message queue, the function fails and returns an error. 

If the argument msg_prio is not NULL, the priority of the selected message is stored in the location referenced by msg_prio. 

If the specified message queue is empty and O_NONBLOCK is not set for the message queue descriptor specified by mqdes, mq_receive() will block until a message is queued on the message queue, or until mq_receive() is interrupted by a signal.  If more than one process is waiting to receive a message when a message arrives at an empty message queue, then the process of the highest scheduling priority is selected to receive the message.  If the specified message queue is empty and O_NONBLOCK is set for the message queue descriptor specified by mqdes, no message is removed from the queue, and mq_receive() returns an error. 

RETURN VALUE

Upon successful completion, the mq_receive() function returns the length of the selected message and the message is removed from the message queue.  If any of the following conditions occur, no message is removed from the queue, a value of -1 is returned, and errno is set to indicate the error:

­[EAGAIN] O_NONBLOCK is set in the message queue description associated with mqdes, and this operation would have blocked because the message queue is empty. 

­[EBADF] The mqdes argument is not a valid message queue descriptor open for reading. 

­[EMSGSIZE] The specified message length, msg_len, is less than the message size attribute of the message queue. 

­[EINTR] A signal interrupted this mq_receive().

FILES

/usr/lib/libposix4.a

SEE ALSO

mq_open(3P4), mq_close(3P4), mq_destroy(3P4), mq_send(3P4), mq_getattr(3P4), mq_notify(3P4), "CX/UX Programmer’s Guide".

WARNING

The interface to mq_receive() is based on IEEE Draft Standard P1003.4/D12.  This is an unapproved draft, subject to change.  Use of information contained in this unapproved draft is at your own risk.  This interface will change to reflect any changes made by future drafts of POSIX 1003.4.