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 .\" $FreeBSD$
  39 .\"
  40 .Dd November 29, 2005
  41 .Dt MQ_RECEIVE 2
  42 .Os
  43 .Sh NAME
  44 .Nm mq_receive , mq_timedreceive
  45 .Nd "receive a message from message queue (REALTIME)"
  46 .Sh LIBRARY
  47 .Lb librt
  48 .Sh SYNOPSIS
  49 .In mqueue.h
  50 .Ft ssize_t
  51 .Fo mq_receive
  52 .Fa "mqd_t mqdes"
  53 .Fa "char *msg_ptr"
  54 .Fa "size_t msg_len"
  55 .Fa "unsigned *msg_prio"
  56 .Fc
  57 .Ft ssize_t
  58 .Fo mq_timedreceive
  59 .Fa "mqd_t mqdes"
  60 .Fa "char *msg_ptr"
  61 .Fa "size_t msg_len"
  62 .Fa "unsigned *msg_prio"
  63 .Fa "const struct timespec *abs_timeout"
  64 .Fc
  65 .Sh DESCRIPTION
  66 The
  67 .Fn mq_receive
  68 system call receives oldest of the highest priority message(s) from the
  69 message queue specified by
  70 .Fa mqdes .
  71 If the size of the buffer in bytes, specified by the
  72 .Fa msg_len
  73 argument, is less than the
  74 .Va mq_msgsize
  75 attribute of the message queue, the system call will fail and return an
  76 error.
  77 Otherwise, the selected message will be removed from the queue
  78 and copied to the buffer pointed to by the
  79 .Fa msg_ptr
  80 argument.
  81 .Pp
  82 If the argument
  83 .Fa msg_prio
  84 is not
  85 .Dv NULL ,
  86 the priority of the selected message will be stored in the
  87 location referenced by
  88 .Fa msg_prio .
  89 If the specified message queue is empty and
  90 .Dv O_NONBLOCK
  91 is not set in the message queue description associated with
  92 .Fa mqdes ,
  93 .Fn mq_receive
  94 will block until a message is enqueued on the message queue or until
  95 .Fn mq_receive
  96 is interrupted by a signal.
  97 If more than one thread is waiting to receive
  98 a message when a message arrives at an empty queue and the Priority
  99 Scheduling option is supported, then the thread of highest priority that
 100 has been waiting the longest will be selected to receive the message.
 101 Otherwise, it is unspecified which waiting thread receives the message.
 102 If the specified message queue is empty and
 103 .Dv O_NONBLOCK
 104 is set in the message queue description associated with
 105 .Fa mqdes ,
 106 no message
 107 will be removed from the queue, and
 108 .Fn mq_receive
 109 will return an error.
 110 .Pp
 111 The
 112 .Fn mq_timedreceive
 113 system call will receive the oldest of the highest priority messages from the
 114 message queue specified by
 115 .Fa mqdes
 116 as described for the
 117 .Fn mq_receive
 118 system call.
 119 However, if
 120 .Dv O_NONBLOCK
 121 was not specified when the message queue was opened via the
 122 .Fn mq_open
 123 system call, and no message exists on the queue to satisfy the receive, the wait
 124 for such a message will be terminated when the specified timeout expires.
 125 If
 126 .Dv O_NONBLOCK
 127 is set, this system call is equivalent to
 128 .Fn mq_receive .
 129 .Pp
 130 The timeout expires when the absolute time specified by
 131 .Fa abs_timeout
 132 passes, as measured by the clock on which timeouts are based (that is, when
 133 the value of that clock equals or exceeds
 134 .Fa abs_timeout ) ,
 135 or if the absolute time specified by
 136 .Fa abs_timeout
 137 has already been passed at the time of the call.
 138 .Pp
 139 The timeout is based on the
 140 .Dv CLOCK_REALTIME
 141 clock.
 142 .Sh RETURN VALUES
 143 Upon successful completion, the
 144 .Fn mq_receive
 145 and
 146 .Fn mq_timedreceive
 147 system calls return the length of the selected message in bytes and the
 148 message is removed from the queue.
 149 Otherwise, no message is removed
 150 from the queue, the system call returns a value of \-1,
 151 and the global variable
 152 .Va errno
 153 is set to indicate the error.
 154 .Sh ERRORS
 155 The
 156 .Fn mq_receive
 157 and
 158 .Fn mq_timedreceive
 159 system calls
 160 will fail if:
 161 .Bl -tag -width Er
 162 .It Bq Er EAGAIN
 163 .Dv O_NONBLOCK
 164 flag is set in the message queue description associated with
 165 .Fa mqdes ,
 166 and the specified message queue is empty.
 167 .It Bq Er EBADF
 168 The
 169 .Fa mqdes
 170 argument is not a valid message queue descriptor open for reading.
 171 .It Bq Er EMSGSIZE
 172 The specified message buffer size,
 173 .Fa msg_len ,
 174 is less than the message size attribute of the message queue.
 175 .It Bq Er EINTR
 176 The
 177 .Fn mq_receive
 178 or
 179 .Fn mq_timedreceive
 180 operation was interrupted by a signal.
 181 .It Bq Er EINVAL
 182 The process or thread would have blocked, and the
 183 .Fa abs_timeout
 184 parameter specified a nanoseconds field value less than zero or greater
 185 than or equal to 1000 million.
 186 .It Bq Er ETIMEDOUT
 187 The
 188 .Dv O_NONBLOCK
 189 flag was not set when the message queue was opened, but no message arrived
 190 on the queue before the specified timeout expired.
 191 .El
 192 .Sh SEE ALSO
 193 .Xr mq_open 2 ,
 194 .Xr mq_send 2 ,
 195 .Xr mq_timedsend 2
 196 .Sh STANDARDS
 197 The
 198 .Fn mq_receive
 199 and
 200 .Fn mq_timedreceive
 201 system calls conform to
 202 .St -p1003.1-2004 .
 203 .Sh HISTORY
 204 Support for
 205 .Tn POSIX
 206 message queues first appeared in
 207 .Fx 7.0 .
 208 .Sh COPYRIGHT
 209 Portions of this text are reprinted and reproduced in electronic form
 210 from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
 211 Portable Operating System Interface (POSIX), The Open Group Base
 212 Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
 213 Electrical and Electronics Engineers, Inc and The Open Group.  In the
 214 event of any discrepancy between this version and the original IEEE and
 215 The Open Group Standard, the original IEEE and The Open Group Standard is
 216 the referee document.  The original Standard can be obtained online at
 217 http://www.opengroup.org/unix/online.html.