1MQ_SEND(3P)                POSIX Programmer's Manual               MQ_SEND(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       mq_send, mq_timedsend — send a message to a message queue (REALTIME)
14

SYNOPSIS

16       #include <mqueue.h>
17
18       int mq_send(mqd_t mqdes, const char *msg_ptr, size_t msg_len,
19           unsigned msg_prio);
20
21       #include <mqueue.h>
22       #include <time.h>
23
24       int mq_timedsend(mqd_t mqdes, const char *msg_ptr, size_t msg_len,
25           unsigned msg_prio, const struct timespec *abstime);
26

DESCRIPTION

28       The mq_send() function shall add the message pointed to by the argument
29       msg_ptr  to the message queue specified by mqdes.  The msg_len argument
30       specifies the length of the message, in bytes, pointed to  by  msg_ptr.
31       The  value  of  msg_len  shall  be less than or equal to the mq_msgsize
32       attribute of the message queue, or mq_send() shall fail.
33
34       If the specified message queue is not full, mq_send() shall  behave  as
35       if the message is inserted into the message queue at the position indi‐
36       cated by the msg_prio argument. A message with a larger  numeric  value
37       of  msg_prio  shall  be  inserted  before messages with lower values of
38       msg_prio.  A message shall be inserted  after  other  messages  in  the
39       queue,  if  any,  with  equal msg_prio.  The value of msg_prio shall be
40       less than {MQ_PRIO_MAX}.
41
42       If the specified message queue is full and O_NONBLOCK is not set in the
43       message  queue description associated with mqdes, mq_send() shall block
44       until  space  becomes  available  to  enqueue  the  message,  or  until
45       mq_send()  is interrupted by a signal. If more than one thread is wait‐
46       ing to send when space becomes available in the message queue  and  the
47       Priority Scheduling option is supported, then the thread of the highest
48       priority that has been waiting the longest shall be unblocked  to  send
49       its  message.  Otherwise,  it  is  unspecified  which waiting thread is
50       unblocked. If the specified message queue is full and O_NONBLOCK is set
51       in  the  message  queue  description associated with mqdes, the message
52       shall not be queued and mq_send() shall return an error.
53
54       The mq_timedsend() function shall add a message to  the  message  queue
55       specified  by  mqdes  in the manner defined for the mq_send() function.
56       However, if the specified message queue is full and O_NONBLOCK  is  not
57       set  in  the  message queue description associated with mqdes, the wait
58       for sufficient room in the queue shall be terminated when the specified
59       timeout expires. If O_NONBLOCK is set in the message queue description,
60       this function shall be equivalent to mq_send().
61
62       The timeout shall expire when the absolute time  specified  by  abstime
63       passes,  as measured by the clock on which timeouts are based (that is,
64       when the value of that clock equals or  exceeds  abstime),  or  if  the
65       absolute  time specified by abstime has already been passed at the time
66       of the call.
67
68       The timeout shall be based on the CLOCK_REALTIME clock.  The resolution
69       of  the  timeout  shall  be  the resolution of the clock on which it is
70       based. The timespec argument is defined in the <time.h> header.
71
72       Under no circumstance shall the operation fail with a timeout if  there
73       is  sufficient  room  in  the queue to add the message immediately. The
74       validity of the abstime parameter need not be  checked  when  there  is
75       sufficient room in the queue.
76

RETURN VALUE

78       Upon  successful completion, the mq_send() and mq_timedsend() functions
79       shall return a value of zero. Otherwise, no message shall be  enqueued,
80       the  functions  shall return −1, and errno shall be set to indicate the
81       error.
82

ERRORS

84       The mq_send() and mq_timedsend() functions shall fail if:
85
86       EAGAIN The O_NONBLOCK flag is set  in  the  message  queue  description
87              associated with mqdes, and the specified message queue is full.
88
89       EBADF  The  mqdes argument is not a valid message queue descriptor open
90              for writing.
91
92       EINTR  A signal interrupted the call to mq_send() or mq_timedsend().
93
94       EINVAL The value of msg_prio was outside the valid range.
95
96       EINVAL The process or thread would have blocked, and the abstime param‐
97              eter  specified  a  nanoseconds  field  value  less than zero or
98              greater than or equal to 1000 million.
99
100       EMSGSIZE
101              The specified message length, msg_len, exceeds the message  size
102              attribute of the message queue.
103
104       ETIMEDOUT
105              The  O_NONBLOCK  flag  was  not  set  when the message queue was
106              opened, but the timeout expired  before  the  message  could  be
107              added to the queue.
108
109       The following sections are informative.
110

EXAMPLES

112       None.
113

APPLICATION USAGE

115       The  value  of  the  symbol {MQ_PRIO_MAX} limits the number of priority
116       levels supported by the application.  Message priorities range  from  0
117       to {MQ_PRIO_MAX}−1.
118

RATIONALE

120       None.
121

FUTURE DIRECTIONS

123       None.
124

SEE ALSO

126       mq_open(), mq_receive(), mq_setattr(), time()
127
128       The Base Definitions volume of POSIX.1‐2008, <mqueue.h>, <time.h>
129
131       Portions  of  this text are reprinted and reproduced in electronic form
132       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
133       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
134       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
135       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
136       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
137       event of any discrepancy between this version and the original IEEE and
138       The Open Group Standard, the original IEEE and The Open Group  Standard
139       is  the  referee document. The original Standard can be obtained online
140       at http://www.unix.org/online.html .
141
142       Any typographical or formatting errors that appear  in  this  page  are
143       most likely to have been introduced during the conversion of the source
144       files to man page format. To report such errors,  see  https://www.ker
145       nel.org/doc/man-pages/reporting_bugs.html .
146
147
148
149IEEE/The Open Group                  2013                          MQ_SEND(3P)
Impressum