lib/librt/mq_receive.3

   1 .\"     $NetBSD$
   2 .\"
   3 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   4 .\"
   5 .Dd January 5, 2009
   6 .Dt MQ_RECEIVE 3
   7 .Os
   8 .Sh NAME
   9 .Nm mq_receive, mq_timedreceive
  10 .Nd receive a message from a message queue (REALTIME)
  11 .Sh LIBRARY
  12 .Lb librt
  13 .Sh SYNOPSIS
  14 .In mqueue.h
  15 .Ft ssize_t
  16 .Fo mq_receive
  17 .Fa "mqd_t mqdes"
  18 .Fa "char *msg_ptr"
  19 .Fa "size_t msg_len"
  20 .Fa "unsigned *msg_prio"
  21 .Fc
  22 .In mqueue.h
  23 .In time.h
  24 .Ft ssize_t
  25 .Fo mq_timedreceive
  26 .Fa "mqd_t mqdes"
  27 .Fa "char *restrict msg_ptr"
  28 .Fa "size_t msg_len"
  29 .Fa "unsigned *restrict msg_prio"
  30 .Fa "const struct timespec *restrict abs_timeout"
  31 .Fc
  32 .Sh DESCRIPTION
  33 The
  34 .Fn mq_receive
  35 function receives the oldest of the highest priority message(s)
  36 from the message queue specified by
  37 .Fa mqdes .
  38 If the size of the buffer in bytes, specified by the
  39 .Fa msg_len
  40 argument, is less than the
  41 .Va mq_msgsize
  42 attribute of the message queue, the function fails and returns an error.
  43 Otherwise, the selected message will be removed from the queue and copied
  44 to the buffer pointed to by the
  45 .Fa msg_ptr
  46 argument.
  47 .Pp
  48 If the argument
  49 .Fa msg_prio
  50 is not
  51 .Dv NULL ,
  52 the priority of the selected message will be stored in the location
  53 referenced by
  54 .Fa msg_prio .
  55 .Pp
  56 If the specified message queue is empty and
  57 .Dv O_NONBLOCK
  58 is not set in the message queue description associated with
  59 .Fa mqdes ,
  60 .Fn mq_receive
  61 blocks until a message is enqueued on the message queue or until
  62 .Fn mq_receive
  63 is interrupted by a signal.
  64 If more than one thread is waiting to receive a message when a
  65 message arrives at an empty queue, then the thread of highest
  66 priority that has been waiting the longest will be selected to
  67 receive the message.
  68 If the specified message queue is empty and
  69 .Dv O_NONBLOCK
  70 is set in the message queue description associated with
  71 .Fa mqdes ,
  72 no message will be removed from the queue, and
  73 .Fn mq_receive
  74 returns an error.
  75 .Pp
  76 The timeout expires when the absolute time specified by
  77 .Fa abs_timeout
  78 passes, as measured by the clock on which timeouts are based (that is,
  79 when the value of that clock equals or exceeds
  80 .Fa abs_timeout ) ,
  81 or if the absolute time specified by
  82 .Fa abs_timeout
  83 has already been passed at the time of the call.
  84 .Pp
  85 The resolution of the timeout is based on the CLOCK_REALTIME clock.
  86 The
  87 .Fa timespec
  88 argument is defined in the
  89 .Aq time.h
  90 header.
  91 .Pp
  92 Under no circumstance will the operation fail with a timeout if a
  93 message can be removed from the message queue immediately.
  94 The validity of the
  95 .Fa abs_timeout
  96 parameter will not be checked if a message can be removed from the
  97 message queue immediately.
  98 .Sh RETURN VALUES
  99 Upon successful completion, the
 100 .Fn mq_receive
 101 and
 102 .Fn mq_timedreceive
 103 functions return a value of zero.
 104 Otherwise, no message will be removed from the queue,
 105 the functions return a value of
 106 \-1, and set the global variable
 107 .Va errno
 108 to indicate the error.
 109 .Sh ERRORS
 110 The
 111 .Fn mq_receive
 112 and
 113 .Fn mq_timedreceive
 114 functions fail if:
 115 .Bl -tag -width Er
 116 .It Bq Er EAGAIN
 117 .Dv O_NONBLOCK
 118 was set in the message description associated with
 119 .Fa mqdes ,
 120 and the specified message queue is empty.
 121 .It Bq Er EBADF
 122 The
 123 .Fa mqdes
 124 argument is not a valid message queue descriptor open for reading.
 125 .It Bq Er EINTR
 126 The
 127 .Fn mq_receive
 128 or
 129 .Fn mq_timedreceive
 130 operation was interrupted by a signal.
 131 .It Bq Er EINVAL
 132 The process or thread would have blocked, and the
 133 .Fa abs_timeout
 134 parameter specified a nanoseconds field value less than zero
 135 or greater than or equal to 1000 million.
 136 .It Bq Er EMSGSIZE
 137 The specified message buffer size,
 138 .Fa msg_len ,
 139 is less than the message size attribute of the message queue.
 140 .It Bq Er ETIMEDOUT
 141 The
 142 .Dv O_NONBLOCK
 143 flag was not set when the message queue was opened,
 144 but no message arrived on the queue before the specified timeout expired.
 145 .El
 146 .Sh SEE ALSO
 147 .Xr mq_close 3 ,
 148 .Xr mq_getattr 3 ,
 149 .Xr mq_notify 3 ,
 150 .Xr mq_open 3 ,
 151 .Xr mq_send 3 ,
 152 .Xr mq_setattr 3 ,
 153 .Xr mq_unlink 3
 154 .Sh STANDARDS
 155 These functions are expected to conform to the
 156 .St -p1003.1-2001
 157 standard.
 158 .Sh HISTORY
 159 The
 160 .Fn mq_receive
 161 and
 162 .Fn mq_timedreceive
 163 functions first appeared in
 164 .Nx 5.0 .
 165 .Sh COPYRIGHT
 166 Portions of this text are reprinted and reproduced in electronic form
 167 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 168 -- Portable Operating System Interface (POSIX), The Open Group Base
 169 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 170 Electrical and Electronics Engineers, Inc and The Open Group.
 171 In the
 172 event of any discrepancy between this version and the original IEEE and
 173 The Open Group Standard, the original IEEE and The Open Group Standard
 174 is the referee document.
 175 The original Standard can be obtained online at
 176 http://www.opengroup.org/unix/online.html .