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