# mq_receive

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           mq_receive, mq_timedreceive — receive a message from a message
           queue (**REALTIME**)
    


## SYNOPSIS



           #include <mqueue.h>
    
           ssize_t mq_receive(mqd_t _mqdes_ , char *_msg_ptr_ , size_t _msg_len_ ,
               unsigned *_msg_prio_);
    
           #include <mqueue.h>
           #include <time.h>
    
           ssize_t mq_timedreceive(mqd_t _mqdes_ , char *restrict _msg_ptr_ ,
               size_t _msg_len_ , unsigned *restrict _msg_prio_ ,
               const struct timespec *restrict _abstime_);
    


## DESCRIPTION



           The _mq_receive_() function shall receive the oldest of the highest
           priority message(s) from the message queue specified by _mqdes_.  If
           the size of the buffer in bytes, specified by the _msg_len_
           argument, is less than the _mq_msgsize_ attribute of the message
           queue, the function shall fail and return an error. Otherwise, the
           selected message shall be removed from the queue and copied to the
           buffer pointed to by the _msg_ptr_ argument.
    
           If the value of _msg_len_ is greater than {SSIZE_MAX}, the result is
           implementation-defined.
    
           If the argument _msg_prio_ is not NULL, the priority of the selected
           message shall be stored in the location referenced by _msg_prio_.
    
           If the specified message queue is empty and O_NONBLOCK is not set
           in the message queue description associated with _mqdes_ ,
           _mq_receive_() shall block until a message is enqueued on the
           message queue or until _mq_receive_() is interrupted by a signal. If
           more than one thread is waiting to receive a message when a
           message arrives at an empty queue and the Priority Scheduling
           option is supported, then the thread of highest priority that has
           been waiting the longest shall be selected to receive the message.
           Otherwise, it is unspecified which waiting thread receives the
           message. If the specified message queue is empty and O_NONBLOCK is
           set in the message queue description associated with _mqdes_ , no
           message shall be removed from the queue, and _mq_receive_() shall
           return an error.
    
           The _mq_timedreceive_() function shall receive the oldest of the
           highest priority messages from the message queue specified by
           _mqdes_ as described for the _mq_receive_() function. However, if
           O_NONBLOCK was not specified when the message queue was opened via
           the _mq_open_() function, and no message exists on the queue to
           satisfy the receive, the wait for such a message shall be
           terminated when the specified timeout expires. If O_NONBLOCK is
           set, this function is equivalent to _mq_receive_().
    
           The timeout expires when the absolute time specified by _abstime_
           passes, as measured by the clock on which timeouts are based (that
           is, when the value of that clock equals or exceeds _abstime_), or if
           the absolute time specified by _abstime_ has already been passed at
           the time of the call.
    
           The timeout shall be based on the CLOCK_REALTIME clock.  The
           resolution of the timeout shall be the resolution of the clock on
           which it is based. The _timespec_ argument is defined in the
           _< time.h>_ header.
    
           Under no circumstance shall the operation fail with a timeout if a
           message can be removed from the message queue immediately. The
           validity of the _abstime_ parameter need not be checked if a message
           can be removed from the message queue immediately.
    


## RETURN VALUE



           Upon successful completion, the _mq_receive_() and _mq_timedreceive_()
           functions shall return the length of the selected message in bytes
           and the message shall be removed from the queue. Otherwise, no
           message shall be removed from the queue, the functions shall
           return a value of -1, and set _errno_ to indicate the error.
    


## ERRORS



           These functions shall fail if:
    
           **EAGAIN** O_NONBLOCK was set in the message description associated
                  with _mqdes_ , and the specified message queue is empty.
    
           **EBADF** The _mqdes_ argument is not a valid message queue descriptor
                  open for reading.
    
           **EMSGSIZE**
                  The specified message buffer size, _msg_len_ , is less than
                  the message size attribute of the message queue.
    
           **EINTR** The _mq_receive_() or _mq_timedreceive_() operation was
                  interrupted by a signal.
    
           **EINVAL** The process or thread would have blocked, and the _abstime_
                  parameter specified a nanoseconds field value less than
                  zero or greater than or equal to 1000 million.
    
           **ETIMEDOUT**
                  The O_NONBLOCK flag was not set when the message queue was
                  opened, but no message arrived on the queue before the
                  specified timeout expired.
    
           These functions may fail if:
    
           **EBADMSG**
                  The implementation has detected a data corruption problem
                  with the message.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *