Debian Codegraph @

upstream/debian-unstable/man3/mq_send.3

raw
1 '\" t
2 .\" Copyright 2006, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH mq_send 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mq_send, mq_timedsend \- send a message to a message queue
10 .SH LIBRARY
11 Real-time library
12 .RI ( librt ,\~ \-lrt )
13 .SH SYNOPSIS
14 .nf
15 .B #include <mqueue.h>
16 .P
17 .BR "int mq_send(" "size_t msg_len;"
18 .BI " mqd_t " mqdes ", const char " msg_ptr [ msg_len ],
19 .BI " size_t " msg_len ", unsigned int " msg_prio );
20 .P
21 .B #include <time.h>
22 .B #include <mqueue.h>
23 .P
24 .BR "int mq_timedsend(" "size_t msg_len;"
25 .BI " mqd_t " mqdes ", const char " msg_ptr [ msg_len ],
26 .BI " size_t " msg_len ", unsigned int " msg_prio ,
27 .BI " const struct timespec *" abs_timeout );
28 .fi
29 .P
30 .ad l
31 .RS -4
32 Feature Test Macro Requirements for glibc (see
33 .BR feature_test_macros (7)):
34 .RE
35 .P
36 .BR mq_timedsend ():
37 .nf
38 _POSIX_C_SOURCE >= 200112L
39 .fi
40 .SH DESCRIPTION
41 .BR mq_send ()
42 adds the message pointed to by
43 .I msg_ptr
44 to the message queue referred to by the message queue descriptor
45 .IR mqdes .
46 The
47 .I msg_len
48 argument specifies the length of the message pointed to by
49 .IR msg_ptr ;
50 this length must be less than or equal to the queue's
51 .I mq_msgsize
52 attribute.
53 Zero-length messages are allowed.
54 .P
55 The
56 .I msg_prio
57 argument is a nonnegative integer that specifies the priority
58 of this message.
59 Messages are placed on the queue in decreasing order of priority,
60 with newer messages of the same priority being placed after
61 older messages with the same priority.
62 See
63 .BR mq_overview (7)
64 for details on the range for the message priority.
65 .P
66 If the message queue is already full
67 (i.e., the number of messages on the queue equals the queue's
68 .I mq_maxmsg
69 attribute), then, by default,
70 .BR mq_send ()
71 blocks until sufficient space becomes available to allow the message
72 to be queued, or until the call is interrupted by a signal handler.
73 If the
74 .B O_NONBLOCK
75 flag is enabled for the message queue description,
76 then the call instead fails immediately with the error
77 .BR EAGAIN .
78 .P
79 .BR mq_timedsend ()
80 behaves just like
81 .BR mq_send (),
82 except that if the queue is full and the
83 .B O_NONBLOCK
84 flag is not enabled for the message queue description, then
85 .I abs_timeout
86 points to a structure which specifies how long the call will block.
87 This value is an absolute timeout in seconds and nanoseconds
88 since the Epoch, 1970-01-01 00:00:00 +0000 (UTC),
89 specified in a
90 .BR timespec (3)
91 structure.
92 .P
93 If the message queue is full,
94 and the timeout has already expired by the time of the call,
95 .BR mq_timedsend ()
96 returns immediately.
97 .SH RETURN VALUE
98 On success,
99 .BR mq_send ()
100 and
101 .BR mq_timedsend ()
102 return zero;
103 on error, \-1 is returned, with
104 .I errno
105 set to indicate the error.
106 .SH ERRORS
107 .TP
108 .B EAGAIN
109 The queue was full, and the
110 .B O_NONBLOCK
111 flag was set for the message queue description referred to by
112 .IR mqdes .
113 .TP
114 .B EBADF
115 The descriptor specified in
116 .I mqdes
117 was invalid or not opened for writing.
118 .TP
119 .B EINTR
120 The call was interrupted by a signal handler;
121 see
122 .BR signal (7).
123 .TP
124 .B EINVAL
125 The call would have blocked, and
126 .I abs_timeout
127 was invalid, either because
128 .I tv_sec
129 was less than zero, or because
130 .I tv_nsec
131 was less than zero or greater than 1000 million.
132 .TP
133 .B EMSGSIZE
134 .I msg_len
135 was greater than the
136 .I mq_msgsize
137 attribute of the message queue.
138 .TP
139 .B ETIMEDOUT
140 The call timed out before a message could be transferred.
141 .SH ATTRIBUTES
142 For an explanation of the terms used in this section, see
143 .BR attributes (7).
144 .TS
145 allbox;
146 lbx lb lb
147 l l l.
148 Interface Attribute Value
149 T{
150 .na
151 .nh
152 .BR mq_send (),
153 .BR mq_timedsend ()
154 T} Thread safety MT-Safe
155 .TE
156 .SH VERSIONS
157 On Linux,
158 .BR mq_timedsend ()
159 is a system call, and
160 .BR mq_send ()
161 is a library function layered on top of that system call.
162 .SH STANDARDS
163 POSIX.1-2008.
164 .SH HISTORY
165 POSIX.1-2001.
166 .SH SEE ALSO
167 .BR mq_close (3),
168 .BR mq_getattr (3),
169 .BR mq_notify (3),
170 .BR mq_open (3),
171 .BR mq_receive (3),
172 .BR mq_unlink (3),
173 .BR timespec (3),
174 .BR mq_overview (7),
175 .BR time (7)