1.\" $NetBSD: mq_send.3,v 1.1 2009/01/05 21:19:49 rmind Exp $ 2.\" 3.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 4.\" 5.Dd August 19, 2009 6.Dt MQ_SEND 2 7.Os 8.Sh NAME 9.Nm mq_send , mq_timedsend 10.Nd send a message to a message queue (REALTIME) 11.Sh LIBRARY 12.Lb librt 13.Sh SYNOPSIS 14.In mqueue.h 15.Ft int 16.Fo mq_send 17.Fa "mqd_t mqdes" 18.Fa "const char *msg_ptr" 19.Fa "size_t msg_len" 20.Fa "unsigned msg_prio" 21.Fc 22.In mqueue.h 23.In time.h 24.Ft int 25.Fo mq_timedsend 26.Fa "mqd_t mqdes" 27.Fa "const char *msg_ptr" 28.Fa "size_t msg_len" 29.Fa "unsigned msg_prio" 30.Fa "const struct timespec *abs_timeout" 31.Fc 32.Sh DESCRIPTION 33The 34.Fn mq_send 35function will add the message pointed to by the argument 36.Fa msg_ptr 37to the message queue specified by 38.Fa mqdes . 39The 40.Fa msg_len 41argument specifies the length of the message, in bytes, pointed to by 42.Fa msg_ptr . 43The value of 44.Fa msg_len 45will be less than or equal to the 46.Fa mq_msgsize 47attribute of the message queue, or 48.Fn mq_send 49will fail. 50.Pp 51If the specified message queue is not full, 52.Fn mq_send 53behaves as if the message is inserted into the message queue at the 54position indicated by the 55.Fa msg_prio 56argument. 57A message with a larger numeric value of 58.Fa msg_prio 59will be inserted before messages with lower values of 60.Fa msg_prio . 61A message will be inserted after other messages in the queue, 62if any, with equal 63.Fa msg_prio . 64The value of 65.Fa msg_prio 66will be less than 67.Brq Dv MQ_PRIO_MAX . 68.Pp 69If the specified message queue is full and 70.Dv O_NONBLOCK 71is not set in the message queue description associated with 72.Fa mqdes , 73.Fn mq_send 74blocks until space becomes available to enqueue the message, or until 75.Fn mq_send 76is interrupted by a signal. 77If more than one thread is waiting to send when space becomes available 78in the message queue, then the thread of the highest priority that has 79been waiting the longest will be unblocked to send its message. 80If the specified message queue is full and 81.Dv O_NONBLOCK 82is set in the message queue description associated with 83.Fa mqdes , 84the message will not be queued and 85.Fn mq_send 86will return an error. 87.Pp 88The 89.Fn mq_timedsend 90function will add a message to the message queue specified by 91.Fa mqdes 92in the manner defined for the 93.Fn mq_send 94function. 95However, if the specified message queue is full and 96.Dv O_NONBLOCK 97is not set in the message queue description associated with 98.Fa mqdes , 99the wait for sufficient room in the queue will be terminated 100when the specified timeout expires. 101If 102.Dv O_NONBLOCK 103is set in the message queue description, this function will be equivalent to 104.Fn mq_send . 105.Pp 106The timeout will expire when the absolute time specified by 107.Fa abs_timeout 108passes, as measured by the clock on which timeouts are based (that is, 109when the value of that clock equals or exceeds 110.Fa abs_timeout ) , 111or if the absolute time specified by 112.Fa abs_timeout 113has already been passed at the time of the call. 114.Pp 115The resolution of the timeout is based on the CLOCK_REALTIME clock. 116The 117.Fa timespec 118argument is defined in the 119.Aq time.h 120header. 121.Pp 122Under no circumstance will the operation fail with a timeout if there is 123sufficient room in the queue to add the message immediately. 124The validity of the 125.Fa abs_timeout 126parameter need not be checked when there is sufficient room in the queue. 127.Sh RETURN VALUES 128Upon successful completion, the 129.Fn mq_send 130and 131.Fn mq_timedsend 132functions return a value of zero. 133Otherwise, no message will be enqueued, 134the functions will return \-1, and the global variable 135.Va errno 136will be set to indicate the error. 137.Sh ERRORS 138The 139.Fn mq_send 140and 141.Fn mq_timedsend 142functions fail if: 143.Bl -tag -width Er 144.It Bq Er EAGAIN 145The 146.Dv O_NONBLOCK 147flag is set in the message queue description associated with 148.Fa mqdes , 149and the specified message queue is full. 150.It Bq Er EBADF 151The 152.Fa mqdes 153argument is not a valid message queue descriptor open for writing. 154.It Bq Er EINTR 155A signal interrupted the call to 156.Fn mq_send 157or 158.Fn mq_timedsend . 159.It Bq Er EINVAL 160The value of 161.Fa msg_prio 162was outside the valid range, or 163the process or thread would have blocked, and the 164.Fa abs_timeout 165parameter specified a nanoseconds field value less than zero 166or greater than or equal to 1000 million. 167.It Bq Er EMSGSIZE 168The specified message length, 169.Fa msg_len , 170exceeds the message size attribute of the message queue. 171.It Bq Er ETIMEDOUT 172The 173.Dv O_NONBLOCK 174flag was not set when the message queue was opened, 175but the timeout expired before the message could be added to the queue. 176.El 177.Sh SEE ALSO 178.Xr mq_close 2 , 179.Xr mq_getattr 2 , 180.Xr mq_notify 2 , 181.Xr mq_open 2 , 182.Xr mq_receive 2 , 183.Xr mq_setattr 2 , 184.Xr mq_unlink 2 185.Sh STANDARDS 186These functions are expected to conform to the 187.St -p1003.1-2001 188standard. 189.Sh HISTORY 190The 191.Fn mq_send 192and 193.Fn mq_timedsend 194functions first appeared in 195.Dx 2.5 . 196.Sh COPYRIGHT 197Portions of this text are reprinted and reproduced in electronic form 198from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology 199-- Portable Operating System Interface (POSIX), The Open Group Base 200Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of 201Electrical and Electronics Engineers, Inc and The Open Group. 202In the 203event of any discrepancy between this version and the original IEEE and 204The Open Group Standard, the original IEEE and The Open Group Standard 205is the referee document. 206The original Standard can be obtained online at 207http://www.opengroup.org/unix/online.html . 208