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