Debian Codegraph @

upstream/debian-unstable/man3/mq_getattr.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_getattr 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 mq_getattr, mq_setattr \- get/set message queue attributes
10 .SH LIBRARY
11 Real-time library
12 .RI ( librt ,\~ \-lrt )
13 .SH SYNOPSIS
14 .nf
15 .B #include <mqueue.h>
16 .P
17 .BI "int mq_getattr(mqd_t " mqdes ", struct mq_attr *" attr );
18 .BI "int mq_setattr(mqd_t " mqdes ", const struct mq_attr *restrict " newattr ,
19 .BI " struct mq_attr *restrict " oldattr );
20 .fi
21 .SH DESCRIPTION
22 .BR mq_getattr ()
23 and
24 .BR mq_setattr ()
25 respectively retrieve and modify attributes of the message queue
26 referred to by the message queue descriptor
27 .IR mqdes .
28 .P
29 .BR mq_getattr ()
30 returns an
31 .I mq_attr
32 structure in the buffer pointed by
33 .IR attr .
34 This structure is defined as:
35 .P
36 .in +4n
37 .EX
38 struct mq_attr {
39 long mq_flags; /* Flags: 0 or O_NONBLOCK */
40 long mq_maxmsg; /* Max.\& # of messages on queue */
41 long mq_msgsize; /* Max.\& message size (bytes) */
42 long mq_curmsgs; /* # of messages currently in queue */
43 };
44 .EE
45 .in
46 .P
47 The
48 .I mq_flags
49 field contains flags associated with the open message queue description.
50 This field is initialized when the queue is created by
51 .BR mq_open (3).
52 The only flag that can appear in this field is
53 .BR O_NONBLOCK .
54 .P
55 The
56 .I mq_maxmsg
57 and
58 .I mq_msgsize
59 fields are set when the message queue is created by
60 .BR mq_open (3).
61 The
62 .I mq_maxmsg
63 field is an upper limit on the number of messages
64 that may be placed on the queue using
65 .BR mq_send (3).
66 The
67 .I mq_msgsize
68 field is an upper limit on the size of messages
69 that may be placed on the queue.
70 Both of these fields must have a value greater than zero.
71 Two
72 .I /proc
73 files that place ceilings on the values for these fields are described in
74 .BR mq_overview (7).
75 .P
76 The
77 .I mq_curmsgs
78 field returns the number of messages currently held in the queue.
79 .P
80 .BR mq_setattr ()
81 sets message queue attributes using information supplied in the
82 .I mq_attr
83 structure pointed to by
84 .IR newattr .
85 The only attribute that can be modified is the setting of the
86 .B O_NONBLOCK
87 flag in
88 .IR mq_flags .
89 The other fields in
90 .I newattr
91 are ignored.
92 If the
93 .I oldattr
94 field is not NULL,
95 then the buffer that it points to is used to return an
96 .I mq_attr
97 structure that contains the same information that is returned by
98 .BR mq_getattr ().
99 .SH RETURN VALUE
100 On success
101 .BR mq_getattr ()
102 and
103 .BR mq_setattr ()
104 return 0;
105 on error, \-1 is returned, with
106 .I errno
107 set to indicate the error.
108 .SH ERRORS
109 .TP
110 .B EBADF
111 The message queue descriptor specified in
112 .I mqdes
113 is invalid.
114 .TP
115 .B EINVAL
116 .I newattr\->mq_flags
117 contained set bits other than
118 .BR O_NONBLOCK .
119 .SH ATTRIBUTES
120 For an explanation of the terms used in this section, see
121 .BR attributes (7).
122 .TS
123 allbox;
124 lbx lb lb
125 l l l.
126 Interface Attribute Value
127 T{
128 .na
129 .nh
130 .BR mq_getattr (),
131 .BR mq_setattr ()
132 T} Thread safety MT-Safe
133 .TE
134 .SH VERSIONS
135 On Linux,
136 .BR mq_getattr ()
137 and
138 .BR mq_setattr ()
139 are library functions layered on top of the
140 .BR mq_getsetattr (2)
141 system call.
142 .SH STANDARDS
143 POSIX.1-2008.
144 .SH HISTORY
145 POSIX.1-2001.
146 .SH EXAMPLES
147 The program below can be used to show the default
148 .I mq_maxmsg
149 and
150 .I mq_msgsize
151 values that are assigned to a message queue that is created with a call to
152 .BR mq_open (3)
153 in which the
154 .I attr
155 argument is NULL.
156 Here is an example run of the program:
157 .P
158 .in +4n
159 .EX
160 .RB $ " ./a.out /testq" ;
161 Maximum # of messages on queue: 10
162 Maximum message size: 8192
163 .EE
164 .in
165 .P
166 Since Linux 3.5, the following
167 .I /proc
168 files (described in
169 .BR mq_overview (7))
170 can be used to control the defaults:
171 .P
172 .in +4n
173 .EX
174 .RB $ " uname \-sr" ;
175 Linux 3.8.0
176 .RB $ " cat /proc/sys/fs/mqueue/msg_default" ;
177 10
178 .RB $ " cat /proc/sys/fs/mqueue/msgsize_default" ;
179 8192
180 .EE
181 .in
182 .SS Program source
183 \&
184 .\" SRC BEGIN (mq_getattr.c)
185 .EX
186 #include <err.h>
187 #include <fcntl.h>
188 #include <mqueue.h>
189 #include <stdio.h>
190 #include <stdlib.h>
191 #include <sys/stat.h>
192 #include <unistd.h>
193 \&
194 int
195 main(int argc, char *argv[])
196 {
197 mqd_t mqd;
198 struct mq_attr attr;
199 \&
200 if (argc != 2) {
201 fprintf(stderr, "Usage: %s mq\-name\[rs]n", argv[0]);
202 exit(EXIT_FAILURE);
203 }
204 \&
205 mqd = mq_open(argv[1], O_CREAT | O_EXCL, 0600, NULL);
206 if (mqd == (mqd_t) \-1)
207 err(EXIT_FAILURE, "mq_open");
208 \&
209 if (mq_getattr(mqd, &attr) == \-1)
210 err(EXIT_FAILURE, "mq_getattr");
211 \&
212 printf("Maximum # of messages on queue: %ld\[rs]n", attr.mq_maxmsg);
213 printf("Maximum message size: %ld\[rs]n", attr.mq_msgsize);
214 \&
215 if (mq_unlink(argv[1]) == \-1)
216 err(EXIT_FAILURE, "mq_unlink");
217 \&
218 exit(EXIT_SUCCESS);
219 }
220 .EE
221 .\" SRC END
222 .SH SEE ALSO
223 .BR mq_close (3),
224 .BR mq_notify (3),
225 .BR mq_open (3),
226 .BR mq_receive (3),
227 .BR mq_send (3),
228 .BR mq_unlink (3),
229 .BR mq_overview (7)