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

NAME

12       mq_send, mq_timedsend - send a message to a message queue (REALTIME)
13

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

85       Upon successful completion, the mq_send()  and mq_timedsend() functions
86       shall  return a value of zero. Otherwise, no message shall be enqueued,
87       the functions shall return -1, and errno shall be set to  indicate  the
88       error.
89

ERRORS

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

EXAMPLES

120       None.
121

APPLICATION USAGE

123       The value of the symbol {MQ_PRIO_MAX} limits  the  number  of  priority
124       levels supported by the application. Message priorities range from 0 to
125       {MQ_PRIO_MAX}-1.
126

RATIONALE

128       None.
129

FUTURE DIRECTIONS

131       None.
132

SEE ALSO

134       mq_open(), mq_receive(), mq_setattr(), mq_timedreceive(),  time(),  the
135       Base Definitions volume of IEEE Std 1003.1-2001, <mqueue.h>, <time.h>
136
138       Portions  of  this text are reprinted and reproduced in electronic form
139       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
140       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
141       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
142       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
143       event of any discrepancy between this version and the original IEEE and
144       The  Open Group Standard, the original IEEE and The Open Group Standard
145       is the referee document. The original Standard can be  obtained  online
146       at http://www.opengroup.org/unix/online.html .
147
148
149
150IEEE/The Open Group                  2003                          MQ_SEND(3P)
Impressum