mq_receive(2)                                                 mq_receive(2)




 NAME    [Toc]    [Back]
      mq_receive - receive a message from a message queue

 SYNOPSIS    [Toc]    [Back]
      #include <sys/mqueue.h>

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

 DESCRIPTION    [Toc]    [Back]
      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    [Toc]    [Back]
      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    [Toc]    [Back]
      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



 Hewlett-Packard Company            - 1 -      HP-UX 11i Version 2: Sep 2004






 mq_receive(2)                                                 mq_receive(2)




                          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.

 SEE ALSO    [Toc]    [Back]
      mq_send(2).

 STANDARDS CONFORMANCE    [Toc]    [Back]
      mq_receive(): POSIX 1003.1b


 Hewlett-Packard Company            - 2 -      HP-UX 11i Version 2: Sep 2004