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

NAME

6       mq_send, mq_timedsend - send a message to a message queue (REALTIME)
7

SYNOPSIS

9       #include <mqueue.h>
10
11       int mq_send(mqd_t mqdes, const char *msg_ptr, size_t msg_len,
12              unsigned msg_prio);
13
14
15
16
17       #include <mqueue.h>
18       #include <time.h>
19       int mq_timedsend(mqd_t mqdes, const char *msg_ptr, size_t msg_len,
20              unsigned msg_prio, const struct timespec *abs_timeout);
21
22

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

114       None.
115

APPLICATION USAGE

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

RATIONALE

122       None.
123

FUTURE DIRECTIONS

125       None.
126

SEE ALSO

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