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-05-28 "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_open (3).
  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 CONFORMING TO
 138 POSIX.1-2001.
 139 .SH NOTES
 140 On Linux,
 141 .BR mq_getattr ()
 142 and
 143 .BR mq_setattr ()
 144 are library functions layered on top of the
 145 .BR mq_getsetattr (2)
 146 system call.
 147 .SH SEE ALSO
 148 .BR mq_close (3),
 149 .BR mq_notify (3),
 150 .BR mq_open (3),
 151 .BR mq_receive (3),
 152 .BR mq_send (3),
 153 .BR mq_unlink (3),
 154 .BR mq_overview (7)
 155 .SH COLOPHON
 156 This page is part of release 3.68 of the Linux
 157 .I man-pages
 158 project.
 159 A description of the project,
 160 information about reporting bugs,
 161 and the latest version of this page,
 162 can be found at
 163 \%http://www.kernel.org/doc/man\-pages/.