lib/libc/sys/mq_receive.2

   1 .\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  17 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
  20 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  23 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  24 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  25 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  26 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" Portions of this text are reprinted and reproduced in electronic form
  29 .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
  30 .\" Portable Operating System Interface (POSIX), The Open Group Base
  31 .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
  32 .\" Electrical and Electronics Engineers, Inc and The Open Group.  In the
  33 .\" event of any discrepancy between this version and the original IEEE and
  34 .\" The Open Group Standard, the original IEEE and The Open Group Standard is
  35 .\" the referee document.  The original Standard can be obtained online at
  36 .\"     http://www.opengroup.org/unix/online.html.
  37 .\"
  38 .Dd November 29, 2005
  39 .Dt MQ_RECEIVE 2
  40 .Os
  41 .Sh NAME
  42 .Nm mq_receive , mq_timedreceive
  43 .Nd "receive a message from message queue (REALTIME)"
  44 .Sh LIBRARY
  45 .Lb librt
  46 .Sh SYNOPSIS
  47 .In mqueue.h
  48 .Ft ssize_t
  49 .Fo mq_receive
  50 .Fa "mqd_t mqdes"
  51 .Fa "char *msg_ptr"
  52 .Fa "size_t msg_len"
  53 .Fa "unsigned *msg_prio"
  54 .Fc
  55 .Ft ssize_t
  56 .Fo mq_timedreceive
  57 .Fa "mqd_t mqdes"
  58 .Fa "char *msg_ptr"
  59 .Fa "size_t msg_len"
  60 .Fa "unsigned *msg_prio"
  61 .Fa "const struct timespec *abs_timeout"
  62 .Fc
  63 .Sh DESCRIPTION
  64 The
  65 .Fn mq_receive
  66 system call receives oldest of the highest priority message(s) from the
  67 message queue specified by
  68 .Fa mqdes .
  69 If the size of the buffer in bytes, specified by the
  70 .Fa msg_len
  71 argument, is less than the
  72 .Va mq_msgsize
  73 attribute of the message queue, the system call will fail and return an
  74 error.
  75 Otherwise, the selected message will be removed from the queue
  76 and copied to the buffer pointed to by the
  77 .Fa msg_ptr
  78 argument.
  79 .Pp
  80 If the argument
  81 .Fa msg_prio
  82 is not
  83 .Dv NULL ,
  84 the priority of the selected message will be stored in the
  85 location referenced by
  86 .Fa msg_prio .
  87 If the specified message queue is empty and
  88 .Dv O_NONBLOCK
  89 is not set in the message queue description associated with
  90 .Fa mqdes ,
  91 .Fn mq_receive
  92 will block until a message is enqueued on the message queue or until
  93 .Fn mq_receive
  94 is interrupted by a signal.
  95 If more than one thread is waiting to receive
  96 a message when a message arrives at an empty queue and the Priority
  97 Scheduling option is supported, then the thread of highest priority that
  98 has been waiting the longest will be selected to receive the message.
  99 Otherwise, it is unspecified which waiting thread receives the message.
 100 If the specified message queue is empty and
 101 .Dv O_NONBLOCK
 102 is set in the message queue description associated with
 103 .Fa mqdes ,
 104 no message
 105 will be removed from the queue, and
 106 .Fn mq_receive
 107 will return an error.
 108 .Pp
 109 The
 110 .Fn mq_timedreceive
 111 system call will receive the oldest of the highest priority messages from the
 112 message queue specified by
 113 .Fa mqdes
 114 as described for the
 115 .Fn mq_receive
 116 system call.
 117 However, if
 118 .Dv O_NONBLOCK
 119 was not specified when the message queue was opened via the
 120 .Fn mq_open
 121 system call, and no message exists on the queue to satisfy the receive, the wait
 122 for such a message will be terminated when the specified timeout expires.
 123 If
 124 .Dv O_NONBLOCK
 125 is set, this system call is equivalent to
 126 .Fn mq_receive .
 127 .Pp
 128 The timeout expires when the absolute time specified by
 129 .Fa abs_timeout
 130 passes, as measured by the clock on which timeouts are based (that is, when
 131 the value of that clock equals or exceeds
 132 .Fa abs_timeout ) ,
 133 or if the absolute time specified by
 134 .Fa abs_timeout
 135 has already been passed at the time of the call.
 136 .Pp
 137 The timeout is based on the
 138 .Dv CLOCK_REALTIME
 139 clock.
 140 .Sh RETURN VALUES
 141 Upon successful completion, the
 142 .Fn mq_receive
 143 and
 144 .Fn mq_timedreceive
 145 system calls return the length of the selected message in bytes and the
 146 message is removed from the queue.
 147 Otherwise, no message is removed
 148 from the queue, the system call returns a value of \-1,
 149 and the global variable
 150 .Va errno
 151 is set to indicate the error.
 152 .Sh ERRORS
 153 The
 154 .Fn mq_receive
 155 and
 156 .Fn mq_timedreceive
 157 system calls
 158 will fail if:
 159 .Bl -tag -width Er
 160 .It Bq Er EAGAIN
 161 .Dv O_NONBLOCK
 162 flag is set in the message queue description associated with
 163 .Fa mqdes ,
 164 and the specified message queue is empty.
 165 .It Bq Er EBADF
 166 The
 167 .Fa mqdes
 168 argument is not a valid message queue descriptor open for reading.
 169 .It Bq Er EMSGSIZE
 170 The specified message buffer size,
 171 .Fa msg_len ,
 172 is less than the message size attribute of the message queue.
 173 .It Bq Er EINTR
 174 The
 175 .Fn mq_receive
 176 or
 177 .Fn mq_timedreceive
 178 operation was interrupted by a signal.
 179 .It Bq Er EINVAL
 180 The process or thread would have blocked, and the
 181 .Fa abs_timeout
 182 parameter specified a nanoseconds field value less than zero or greater
 183 than or equal to 1000 million.
 184 .It Bq Er ETIMEDOUT
 185 The
 186 .Dv O_NONBLOCK
 187 flag was not set when the message queue was opened, but no message arrived
 188 on the queue before the specified timeout expired.
 189 .El
 190 .Sh SEE ALSO
 191 .Xr mq_open 2 ,
 192 .Xr mq_send 2 ,
 193 .Xr mq_timedsend 2
 194 .Sh STANDARDS
 195 The
 196 .Fn mq_receive
 197 and
 198 .Fn mq_timedreceive
 199 system calls conform to
 200 .St -p1003.1-2004 .
 201 .Sh HISTORY
 202 Support for
 203 .Tn POSIX
 204 message queues first appeared in
 205 .Fx 7.0 .
 206 .Sh COPYRIGHT
 207 Portions of this text are reprinted and reproduced in electronic form
 208 from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
 209 Portable Operating System Interface (POSIX), The Open Group Base
 210 Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
 211 Electrical and Electronics Engineers, Inc and The Open Group.  In the
 212 event of any discrepancy between this version and the original IEEE and
 213 The Open Group Standard, the original IEEE and The Open Group Standard is
 214 the referee document.  The original Standard can be obtained online at
 215 http://www.opengroup.org/unix/online.html.