NAME    [Toc]    [Back]

       mq_receive - Receives the oldest, highest-priority message
       from the message queue (P1003.1b)

SYNOPSIS    [Toc]    [Back]

       #include <mqueue.h>

       ssize_t mq_receive ( mqd_t mqdes,  char  *msg_ptr,  size_t
       msg_len, unsigned int *msg_prio);

LIBRARY    [Toc]    [Back]

       Realtime Library (librt.so, librt.a)

PARAMETERS    [Toc]    [Back]

       Specifies  a  message  queue  by  descriptor.  Specifies a
       pointer to a buffer to receive the message.  Specifies the
       size of the receive buffer identified by the msg_ptr argument.
  Specifies a pointer to a location  to  receive  the
       message priority.

DESCRIPTION    [Toc]    [Back]

       The  mq_receive function receives the oldest, highest-priority
 message from  the  message  queue.  The  message  is
       removed  from  the  queue  and  transferred  to the buffer
       pointed to by the msg_ptr argument.

       If the specified message queue is empty and the O_NONBLOCK
       option  is not set with the mqdes argument, the mq_receive
       function blocks until a message is put  on  the  queue  or
       until  the mq_receive function is interrupted by a signal.
       If more than one process is waiting to receive  a  message
       when a message arrives at an empty queue, the highest-priority
  process  that  has  been  waiting  the  longest  is
       selected  to receive the message.  If the message queue is
       empty and the O_NONBLOCK option  is  set,  no  message  is
       removed from the queue, and an error is returned.

RETURN VALUES    [Toc]    [Back]

       On  successful completion, the function returns the length
       of the selected message.

       Otherwise, the function returns  the  value  -1  and  sets
       errno  to  indicate the error.  No message is removed from
       the queue.

ERRORS    [Toc]    [Back]

       The mq_receive function fails under the  following  conditions:
 O_NONBLOCK was set in the message description associated
 with mqdes, and  the  specified  message  queue  is
       empty.   The  mqdes  argument is not a valid message queue
       descriptor  open  for  reading.   The  implementation  has
       detected  a  data corruption problem with the message.  An
       internal virtual memory error  occurred.   The  mq_receive
       function  was interrupted by a signal.  The specified message
 buffer size, msg_len, is less than the  message  size
       attribute of the message queue.

SEE ALSO    [Toc]    [Back]

       Functions: mq_send(3)

       Guide to Realtime Programming



                                                    mq_receive(3)