man3/mq_getattr.3

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