man3/mq_getattr.3

   1 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH MQ_GETATTR 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 mq_getattr, mq_setattr \- get/set message queue attributes
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <mqueue.h>
  31 .PP
  32 .BI "int mq_getattr(mqd_t " mqdes ", struct mq_attr *" attr );
  33 .BI "int mq_setattr(mqd_t " mqdes ", const struct mq_attr *restrict " newattr ,
  34 .BI "               struct mq_attr *restrict " oldattr );
  35 .fi
  36 .PP
  37 Link with \fI\-lrt\fP.
  38 .SH DESCRIPTION
  39 .BR mq_getattr ()
  40 and
  41 .BR mq_setattr ()
  42 respectively retrieve and modify attributes of the message queue
  43 referred to by the message queue descriptor
  44 .IR mqdes .
  45 .PP
  46 .BR mq_getattr ()
  47 returns an
  48 .I mq_attr
  49 structure in the buffer pointed by
  50 .IR attr .
  51 This structure is defined as:
  52 .PP
  53 .in +4n
  54 .EX
  55 struct mq_attr {
  56     long mq_flags;       /* Flags: 0 or O_NONBLOCK */
  57     long mq_maxmsg;      /* Max. # of messages on queue */
  58     long mq_msgsize;     /* Max. message size (bytes) */
  59     long mq_curmsgs;     /* # of messages currently in queue */
  60 };
  61 .EE
  62 .in
  63 .PP
  64 The
  65 .I mq_flags
  66 field contains flags associated with the open message queue description.
  67 This field is initialized when the queue is created by
  68 .BR mq_open (3).
  69 The only flag that can appear in this field is
  70 .BR O_NONBLOCK .
  71 .PP
  72 The
  73 .I mq_maxmsg
  74 and
  75 .I mq_msgsize
  76 fields are set when the message queue is created by
  77 .BR mq_open (3).
  78 The
  79 .I mq_maxmsg
  80 field is an upper limit on the number of messages
  81 that may be placed on the queue using
  82 .BR mq_send (3).
  83 The
  84 .I mq_msgsize
  85 field is an upper limit on the size of messages
  86 that may be placed on the queue.
  87 Both of these fields must have a value greater than zero.
  88 Two
  89 .I /proc
  90 files that place ceilings on the values for these fields are described in
  91 .BR mq_overview (7).
  92 .PP
  93 The
  94 .I mq_curmsgs
  95 field returns the number of messages currently held in the queue.
  96 .PP
  97 .BR mq_setattr ()
  98 sets message queue attributes using information supplied in the
  99 .I mq_attr
 100 structure pointed to by
 101 .IR newattr .
 102 The only attribute that can be modified is the setting of the
 103 .B O_NONBLOCK
 104 flag in
 105 .IR mq_flags .
 106 The other fields in
 107 .I newattr
 108 are ignored.
 109 If the
 110 .I oldattr
 111 field is not NULL,
 112 then the buffer that it points to is used to return an
 113 .I mq_attr
 114 structure that contains the same information that is returned by
 115 .BR mq_getattr ().
 116 .SH RETURN VALUE
 117 On success
 118 .BR mq_getattr ()
 119 and
 120 .BR mq_setattr ()
 121 return 0; on error, \-1 is returned, with
 122 .I errno
 123 set to indicate the error.
 124 .SH ERRORS
 125 .TP
 126 .B EBADF
 127 The message queue descriptor specified in
 128 .I mqdes
 129 is invalid.
 130 .TP
 131 .B EINVAL
 132 .I newattr\->mq_flags
 133 contained set bits other than
 134 .BR O_NONBLOCK .
 135 .SH ATTRIBUTES
 136 For an explanation of the terms used in this section, see
 137 .BR attributes (7).
 138 .ad l
 139 .nh
 140 .TS
 141 allbox;
 142 lbx lb lb
 143 l l l.
 144 Interface       Attribute       Value
 145 T{
 146 .BR mq_getattr (),
 147 .BR mq_setattr ()
 148 T}      Thread safety   MT-Safe
 149 .TE
 150 .hy
 151 .ad
 152 .sp 1
 153 .SH CONFORMING TO
 154 POSIX.1-2001, POSIX.1-2008.
 155 .SH NOTES
 156 On Linux,
 157 .BR mq_getattr ()
 158 and
 159 .BR mq_setattr ()
 160 are library functions layered on top of the
 161 .BR mq_getsetattr (2)
 162 system call.
 163 .SH EXAMPLES
 164 The program below can be used to show the default
 165 .I mq_maxmsg
 166 and
 167 .I mq_msgsize
 168 values that are assigned to a message queue that is created with a call to
 169 .BR mq_open (3)
 170 in which the
 171 .I attr
 172 argument is NULL.
 173 Here is an example run of the program:
 174 .PP
 175 .in +4n
 176 .EX
 177 $ \fB./a.out /testq\fP
 178 Maximum # of messages on queue:   10
 179 Maximum message size:             8192
 180 .EE
 181 .in
 182 .PP
 183 Since Linux 3.5, the following
 184 .I /proc
 185 files (described in
 186 .BR mq_overview (7))
 187 can be used to control the defaults:
 188 .PP
 189 .in +4n
 190 .EX
 191 $ \fBuname \-sr\fP
 192 Linux 3.8.0
 193 $ \fBcat /proc/sys/fs/mqueue/msg_default\fP
 194 10
 195 $ \fBcat /proc/sys/fs/mqueue/msgsize_default\fP
 196 8192
 197 .EE
 198 .in
 199 .SS Program source
 200 \&
 201 .EX
 202 #include <mqueue.h>
 203 #include <sys/stat.h>
 204 #include <fcntl.h>
 205 #include <stdio.h>
 206 #include <stdlib.h>
 207 #include <unistd.h>
 208
 209 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 210                         } while (0)
 211
 212 int
 213 main(int argc, char *argv[])
 214 {
 215     mqd_t mqd;
 216     struct mq_attr attr;
 217
 218     if (argc != 2) {
 219         fprintf(stderr, "Usage: %s mq\-name\en", argv[0]);
 220         exit(EXIT_FAILURE);
 221     }
 222
 223     mqd = mq_open(argv[1], O_CREAT | O_EXCL, S_IRUSR | S_IWUSR, NULL);
 224     if (mqd == (mqd_t) \-1)
 225         errExit("mq_open");
 226
 227     if (mq_getattr(mqd, &attr) == \-1)
 228         errExit("mq_getattr");
 229
 230     printf("Maximum # of messages on queue:   %ld\en", attr.mq_maxmsg);
 231     printf("Maximum message size:             %ld\en", attr.mq_msgsize);
 232
 233     if (mq_unlink(argv[1]) == \-1)
 234         errExit("mq_unlink");
 235
 236     exit(EXIT_SUCCESS);
 237 }
 238 .EE
 239 .SH SEE ALSO
 240 .BR mq_close (3),
 241 .BR mq_notify (3),
 242 .BR mq_open (3),
 243 .BR mq_receive (3),
 244 .BR mq_send (3),
 245 .BR mq_unlink (3),
 246 .BR mq_overview (7)