1MQ_GETATTR(3) Linux Programmer's Manual MQ_GETATTR(3)
2
3
4
6 mq_getattr, mq_setattr - get/set message queue attributes
7
9 #include <mqueue.h>
10
11 int mq_getattr(mqd_t mqdes, struct mq_attr *attr);
12 int mq_setattr(mqd_t mqdes, const struct mq_attr *restrict newattr,
13 struct mq_attr *restrict oldattr);
14
15 Link with -lrt.
16
18 mq_getattr() and mq_setattr() respectively retrieve and modify at‐
19 tributes of the message queue referred to by the message queue descrip‐
20 tor mqdes.
21
22 mq_getattr() returns an mq_attr structure in the buffer pointed by
23 attr. This structure is defined as:
24
25 struct mq_attr {
26 long mq_flags; /* Flags: 0 or O_NONBLOCK */
27 long mq_maxmsg; /* Max. # of messages on queue */
28 long mq_msgsize; /* Max. message size (bytes) */
29 long mq_curmsgs; /* # of messages currently in queue */
30 };
31
32 The mq_flags field contains flags associated with the open message
33 queue description. This field is initialized when the queue is created
34 by mq_open(3). The only flag that can appear in this field is O_NON‐
35 BLOCK.
36
37 The mq_maxmsg and mq_msgsize fields are set when the message queue is
38 created by mq_open(3). The mq_maxmsg field is an upper limit on the
39 number of messages that may be placed on the queue using mq_send(3).
40 The mq_msgsize field is an upper limit on the size of messages that may
41 be placed on the queue. Both of these fields must have a value greater
42 than zero. Two /proc files that place ceilings on the values for these
43 fields are described in mq_overview(7).
44
45 The mq_curmsgs field returns the number of messages currently held in
46 the queue.
47
48 mq_setattr() sets message queue attributes using information supplied
49 in the mq_attr structure pointed to by newattr. The only attribute
50 that can be modified is the setting of the O_NONBLOCK flag in mq_flags.
51 The other fields in newattr are ignored. If the oldattr field is not
52 NULL, then the buffer that it points to is used to return an mq_attr
53 structure that contains the same information that is returned by
54 mq_getattr().
55
57 On success mq_getattr() and mq_setattr() return 0; on error, -1 is re‐
58 turned, with errno set to indicate the error.
59
61 EBADF The message queue descriptor specified in mqdes is invalid.
62
63 EINVAL newattr->mq_flags contained set bits other than O_NONBLOCK.
64
66 For an explanation of the terms used in this section, see at‐
67 tributes(7).
68
69 ┌────────────────────────────────────────────┬───────────────┬─────────┐
70 │Interface │ Attribute │ Value │
71 ├────────────────────────────────────────────┼───────────────┼─────────┤
72 │mq_getattr(), mq_setattr() │ Thread safety │ MT-Safe │
73 └────────────────────────────────────────────┴───────────────┴─────────┘
74
76 POSIX.1-2001, POSIX.1-2008.
77
79 On Linux, mq_getattr() and mq_setattr() are library functions layered
80 on top of the mq_getsetattr(2) system call.
81
83 The program below can be used to show the default mq_maxmsg and mq_msg‐
84 size values that are assigned to a message queue that is created with a
85 call to mq_open(3) in which the attr argument is NULL. Here is an ex‐
86 ample run of the program:
87
88 $ ./a.out /testq
89 Maximum # of messages on queue: 10
90 Maximum message size: 8192
91
92 Since Linux 3.5, the following /proc files (described in mq_over‐
93 view(7)) can be used to control the defaults:
94
95 $ uname -sr
96 Linux 3.8.0
97 $ cat /proc/sys/fs/mqueue/msg_default
98 10
99 $ cat /proc/sys/fs/mqueue/msgsize_default
100 8192
101
102 Program source
103
104 #include <mqueue.h>
105 #include <sys/stat.h>
106 #include <fcntl.h>
107 #include <stdio.h>
108 #include <stdlib.h>
109 #include <unistd.h>
110
111 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
112 } while (0)
113
114 int
115 main(int argc, char *argv[])
116 {
117 mqd_t mqd;
118 struct mq_attr attr;
119
120 if (argc != 2) {
121 fprintf(stderr, "Usage: %s mq-name\n", argv[0]);
122 exit(EXIT_FAILURE);
123 }
124
125 mqd = mq_open(argv[1], O_CREAT | O_EXCL, S_IRUSR | S_IWUSR, NULL);
126 if (mqd == (mqd_t) -1)
127 errExit("mq_open");
128
129 if (mq_getattr(mqd, &attr) == -1)
130 errExit("mq_getattr");
131
132 printf("Maximum # of messages on queue: %ld\n", attr.mq_maxmsg);
133 printf("Maximum message size: %ld\n", attr.mq_msgsize);
134
135 if (mq_unlink(argv[1]) == -1)
136 errExit("mq_unlink");
137
138 exit(EXIT_SUCCESS);
139 }
140
142 mq_close(3), mq_notify(3), mq_open(3), mq_receive(3), mq_send(3),
143 mq_unlink(3), mq_overview(7)
144
146 This page is part of release 5.13 of the Linux man-pages project. A
147 description of the project, information about reporting bugs, and the
148 latest version of this page, can be found at
149 https://www.kernel.org/doc/man-pages/.
150
151
152
153Linux 2021-03-22 MQ_GETATTR(3)