lib/libc/sys/mq_send.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_SEND 2
  42 .Os
  43 .Sh NAME
  44 .Nm mq_send , mq_timedsend
  45 .Nd "send a message to message queue (REALTIME)"
  46 .Sh LIBRARY
  47 .Lb librt
  48 .Sh SYNOPSIS
  49 .In mqueue.h
  50 .Ft int
  51 .Fo mq_send
  52 .Fa "mqd_t mqdes"
  53 .Fa "const char *msg_ptr"
  54 .Fa "size_t msg_len"
  55 .Fa "unsigned msg_prio"
  56 .Fc
  57 .Ft int
  58 .Fo mq_timedsend
  59 .Fa "mqd_t mqdes"
  60 .Fa "const 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_send
  68 system call adds the message pointed to by the argument
  69 .Fa msg_ptr
  70 to the message queue specified by
  71 .Fa mqdes .
  72 The
  73 .Fa msg_len
  74 argument specifies the length of the message, in bytes, pointed to by
  75 .Fa msg_ptr .
  76 The value of
  77 .Fa msg_len
  78 should be less than or equal to the
  79 .Va mq_msgsize
  80 attribute of the message queue, or
  81 .Fn mq_send
  82 will fail.
  83 .Pp
  84 If the specified message queue is not full,
  85 .Fn mq_send
  86 will behave as if the message is inserted into the message queue at
  87 the position indicated by the
  88 .Fa msg_prio
  89 argument.
  90 A message with a larger numeric value of
  91 .Fa msg_prio
  92 will be inserted before messages with lower values of
  93 .Fa msg_prio .
  94 A message will be inserted after other messages in the queue, if any,
  95 with equal
  96 .Fa msg_prio .
  97 The value of
  98 .Fa msg_prio
  99 should be less than
 100 .Brq Dv MQ_PRIO_MAX .
 101 .Pp
 102 If the specified message queue is full and
 103 .Dv O_NONBLOCK
 104 is not set in the message queue description associated with
 105 .Fa mqdes ,
 106 .Fn mq_send
 107 will block until space becomes available to enqueue the
 108 message, or until
 109 .Fn mq_send
 110 is interrupted by a signal.
 111 If more than one thread is
 112 waiting to send when space becomes available in the message queue and
 113 the Priority Scheduling option is supported, then the thread of the
 114 highest priority that has been waiting the longest will be unblocked
 115 to send its message.
 116 Otherwise, it is unspecified which waiting thread
 117 is unblocked.
 118 If the specified message queue is full and
 119 .Dv O_NONBLOCK
 120 is set in the message queue description associated with
 121 .Fa mqdes ,
 122 the message will not be queued and
 123 .Fn mq_send
 124 will return an error.
 125 .Pp
 126 The
 127 .Fn mq_timedsend
 128 system call will add a message to the message queue specified by
 129 .Fa mqdes
 130 in the manner defined for the
 131 .Fn mq_send
 132 system call.
 133 However, if the specified message queue is full and
 134 .Dv O_NONBLOCK
 135 is not set in the message queue description associated with
 136 .Fa mqdes ,
 137 the wait for sufficient room in the queue will be terminated when
 138 the specified timeout expires.
 139 If
 140 .Dv O_NONBLOCK
 141 is set in the message queue description, this system call is
 142 equivalent to
 143 .Fn mq_send .
 144 .Pp
 145 The timeout will expire when the absolute time specified by
 146 .Fa abs_timeout
 147 passes, as measured by the clock on which timeouts are based (that is,
 148 when the value of that clock equals or exceeds
 149 .Fa abs_timeout ) ,
 150 or if the absolute time specified by
 151 .Fa abs_timeout
 152 has already been passed at the time of the call.
 153 .Pp
 154 The timeout is based on the
 155 .Dv CLOCK_REALTIME
 156 clock.
 157 .Sh RETURN VALUES
 158 Upon successful completion, the
 159 .Fn mq_send
 160 and
 161 .Fn mq_timedsend
 162 system calls return a value of zero.
 163 Otherwise, no message will be
 164 enqueued, the system calls return \-1, and
 165 the global variable
 166 .Va errno
 167 is set to indicate the error.
 168 .Sh ERRORS
 169 The
 170 .Fn mq_send
 171 and
 172 .Fn mq_timedsend
 173 system calls
 174 will fail if:
 175 .Bl -tag -width Er
 176 .It Bq Er EAGAIN
 177 The
 178 .Dv O_NONBLOCK
 179 flag is set in the message queue description associated with
 180 .Fa mqdes ,
 181 and the specified message queue is full.
 182 .It Bq Er EBADF
 183 The
 184 .Fa mqdes
 185 argument is not a valid message queue descriptor open for writing.
 186 .It Bq Er EINTR
 187 A signal interrupted the call to
 188 .Fn mq_send
 189 or
 190 .Fn mq_timedsend .
 191 .It Bq Er EINVAL
 192 The value of
 193 .Fa msg_prio
 194 was outside the valid range.
 195 .It Bq Er EINVAL
 196 The process or thread would have blocked, and the
 197 .Fa abs_timeout
 198 parameter specified a nanoseconds field value less than zero or greater
 199 than or equal to 1000 million.
 200 .It Bq Er EMSGSIZE
 201 The specified message length,
 202 .Fa msg_len ,
 203 exceeds the message size attribute of the message queue.
 204 .It Bq Er ETIMEDOUT
 205 The
 206 .Dv O_NONBLOCK
 207 flag was not set when the message queue was opened, but the timeout
 208 expired before the message could be added to the queue.
 209 .El
 210 .Sh SEE ALSO
 211 .Xr mq_open 2 ,
 212 .Xr mq_receive 2 ,
 213 .Xr mq_setattr 2 ,
 214 .Xr mq_timedreceive 2
 215 .Sh STANDARDS
 216 The
 217 .Fn mq_send
 218 and
 219 .Fn mq_timedsend
 220 system calls conform to
 221 .St -p1003.1-2004 .
 222 .Sh HISTORY
 223 Support for
 224 .Tn POSIX
 225 message queues first appeared in
 226 .Fx 7.0 .
 227 .Sh COPYRIGHT
 228 Portions of this text are reprinted and reproduced in electronic form
 229 from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
 230 Portable Operating System Interface (POSIX), The Open Group Base
 231 Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
 232 Electrical and Electronics Engineers, Inc and The Open Group.  In the
 233 event of any discrepancy between this version and the original IEEE and
 234 The Open Group Standard, the original IEEE and The Open Group Standard is
 235 the referee document.  The original Standard can be obtained online at
 236 http://www.opengroup.org/unix/online.html.