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