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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .PP
  75 The
  76 .I mq_curmsgs
  77 field returns the number of messages currently held in the queue.
  78 .PP
  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 .sp 1
 133 .SH VERSIONS
 134 On Linux,
 135 .BR mq_getattr ()
 136 and
 137 .BR mq_setattr ()
 138 are library functions layered on top of the
 139 .BR mq_getsetattr (2)
 140 system call.
 141 .SH STANDARDS
 142 POSIX.1-2008.
 143 .SH HISTORY
 144 POSIX.1-2001.
 145 .SH EXAMPLES
 146 The program below can be used to show the default
 147 .I mq_maxmsg
 148 and
 149 .I mq_msgsize
 150 values that are assigned to a message queue that is created with a call to
 151 .BR mq_open (3)
 152 in which the
 153 .I attr
 154 argument is NULL.
 155 Here is an example run of the program:
 156 .PP
 157 .in +4n
 158 .EX
 159 $ \fB./a.out /testq\fP
 160 Maximum # of messages on queue:   10
 161 Maximum message size:             8192
 162 .EE
 163 .in
 164 .PP
 165 Since Linux 3.5, the following
 166 .I /proc
 167 files (described in
 168 .BR mq_overview (7))
 169 can be used to control the defaults:
 170 .PP
 171 .in +4n
 172 .EX
 173 $ \fBuname \-sr\fP
 174 Linux 3.8.0
 175 $ \fBcat /proc/sys/fs/mqueue/msg_default\fP
 176 10
 177 $ \fBcat /proc/sys/fs/mqueue/msgsize_default\fP
 178 8192
 179 .EE
 180 .in
 181 .SS Program source
 182 \&
 183 .\" SRC BEGIN (mq_getattr.c)
 184 .EX
 185 #include <fcntl.h>
 186 #include <mqueue.h>
 187 #include <stdio.h>
 188 #include <stdlib.h>
 189 #include <sys/stat.h>
 190 #include <unistd.h>
 191 \&
 192 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 193                         } while (0)
 194 \&
 195 int
 196 main(int argc, char *argv[])
 197 {
 198     mqd_t mqd;
 199     struct mq_attr attr;
 200 \&
 201     if (argc != 2) {
 202         fprintf(stderr, "Usage: %s mq\-name\en", argv[0]);
 203         exit(EXIT_FAILURE);
 204     }
 205 \&
 206     mqd = mq_open(argv[1], O_CREAT | O_EXCL, 0600, NULL);
 207     if (mqd == (mqd_t) \-1)
 208         errExit("mq_open");
 209 \&
 210     if (mq_getattr(mqd, &attr) == \-1)
 211         errExit("mq_getattr");
 212 \&
 213     printf("Maximum # of messages on queue:   %ld\en", attr.mq_maxmsg);
 214     printf("Maximum message size:             %ld\en", attr.mq_msgsize);
 215 \&
 216     if (mq_unlink(argv[1]) == \-1)
 217         errExit("mq_unlink");
 218 \&
 219     exit(EXIT_SUCCESS);
 220 }
 221 .EE
 222 .\" SRC END
 223 .SH SEE ALSO
 224 .BR mq_close (3),
 225 .BR mq_notify (3),
 226 .BR mq_open (3),
 227 .BR mq_receive (3),
 228 .BR mq_send (3),
 229 .BR mq_unlink (3),
 230 .BR mq_overview (7)