original/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 2014-10-02 "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 .sp
  33 .BI "int mq_getattr(mqd_t " mqdes ", struct mq_attr *" attr );
  34
  35 .BI "int mq_setattr(mqd_t " mqdes ", const struct mq_attr *" newattr ","
  36 .BI "                 struct mq_attr *" oldattr );
  37 .fi
  38 .sp
  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 descriptor
  46 .IR mqdes .
  47
  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 .in +4n
  55 .nf
  56
  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 .fi
  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
  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
  95 The
  96 .I mq_curmsgs
  97 field returns the number of messages currently held in the queue.
  98
  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 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 .SS Multithreading (see pthreads(7))
 139 The
 140 .BR mq_getattr ()
 141 and
 142 .BR mq_setattr ()
 143 functions are thread-safe.
 144 .SH CONFORMING TO
 145 POSIX.1-2001.
 146 .SH NOTES
 147 On Linux,
 148 .BR mq_getattr ()
 149 and
 150 .BR mq_setattr ()
 151 are library functions layered on top of the
 152 .BR mq_getsetattr (2)
 153 system call.
 154 .SH EXAMPLE
 155 The program below can be used to show the default
 156 .I mq_maxmsg
 157 and
 158 .I mq_msgsize
 159 values that are assigned to a message queue that is created with a call to
 160 .BR mq_open (3)
 161 in which the
 162 .I attr
 163 argument is NULL.
 164 Here is an example run of the program:
 165
 166 .in +4n
 167 .nf
 168 $ \fB./a.out /testq\fP
 169 Maximum # of messages on queue:   10
 170 Maximum message size:             8192
 171 .fi
 172 .in
 173
 174 Since Linux 3.5, the following
 175 .I /proc
 176 files (described in
 177 .BR mq_overview (7))
 178 can be used to control the defaults:
 179
 180 .in +4n
 181 .nf
 182 $ \fBuname -sr\fP
 183 Linux 3.8.0
 184 $ \fBcat /proc/sys/fs/mqueue/msg_default\fP
 185 10
 186 $ \fBcat /proc/sys/fs/mqueue/msgsize_default\fP
 187 8192
 188 .fi
 189 .in
 190 .SS Program source
 191 \&
 192 .nf
 193 #include <mqueue.h>
 194 #include <sys/stat.h>
 195 #include <fcntl.h>
 196 #include <stdio.h>
 197 #include <stdlib.h>
 198 #include <unistd.h>
 199
 200 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
 201                         } while (0)
 202
 203 int
 204 main(int argc, char *argv[])
 205 {
 206     mqd_t mqd;
 207     struct mq_attr attr;
 208
 209     if (argc != 2) {
 210         fprintf(stderr, "Usage: %s mq\-name\\n", argv[0]);
 211         exit(EXIT_FAILURE);
 212     }
 213
 214     mqd = mq_open(argv[1], O_CREAT | O_EXCL, S_IRUSR | S_IWUSR, NULL);
 215     if (mqd == (mqd_t) \-1)
 216         errExit("mq_open");
 217
 218     if (mq_getattr(mqd, &attr) == \-1)
 219         errExit("mq_getattr");
 220
 221     printf("Maximum # of messages on queue:   %ld\\n", attr.mq_maxmsg);
 222     printf("Maximum message size:             %ld\\n", attr.mq_msgsize);
 223
 224     if (mq_unlink(argv[1]) == \-1)
 225         errExit("mq_unlink");
 226
 227     exit(EXIT_SUCCESS);
 228 }
 229 .fi
 230 .SH SEE ALSO
 231 .BR mq_close (3),
 232 .BR mq_notify (3),
 233 .BR mq_open (3),
 234 .BR mq_receive (3),
 235 .BR mq_send (3),
 236 .BR mq_unlink (3),
 237 .BR mq_overview (7)
 238 .SH COLOPHON
 239 This page is part of release 3.78 of the Linux
 240 .I man-pages
 241 project.
 242 A description of the project,
 243 information about reporting bugs,
 244 and the latest version of this page,
 245 can be found at
 246 \%http://www.kernel.org/doc/man\-pages/.