man3/mq_getattr.3

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