man3/mq_open.3

   1 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH MQ_OPEN 3 2021-03-22 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 mq_open \- open a message queue
  28 .SH SYNOPSIS
  29 .nf
  30 .BR "#include <fcntl.h>" "           /* For O_* constants */"
  31 .BR "#include <sys/stat.h>" "        /* For mode constants */"
  32 .B #include <mqueue.h>
  33 .PP
  34 .BI "mqd_t mq_open(const char *" name ", int " oflag );
  35 .BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode ,
  36 .BI "              struct mq_attr *" attr );
  37 .fi
  38 .PP
  39 Link with \fI\-lrt\fP.
  40 .SH DESCRIPTION
  41 .BR mq_open ()
  42 creates a new POSIX message queue or opens an existing queue.
  43 The queue is identified by
  44 .IR name .
  45 For details of the construction of
  46 .IR name ,
  47 see
  48 .BR mq_overview (7).
  49 .PP
  50 The
  51 .I oflag
  52 argument specifies flags that control the operation of the call.
  53 (Definitions of the flags values can be obtained by including
  54 .IR <fcntl.h> .)
  55 Exactly one of the following must be specified in
  56 .IR oflag :
  57 .TP
  58 .B O_RDONLY
  59 Open the queue to receive messages only.
  60 .TP
  61 .B O_WRONLY
  62 Open the queue to send messages only.
  63 .TP
  64 .B O_RDWR
  65 Open the queue to both send and receive messages.
  66 .PP
  67 Zero or more of the following flags can additionally be
  68 .IR OR ed
  69 in
  70 .IR oflag :
  71 .TP
  72 .BR O_CLOEXEC " (since Linux 2.6.26)"
  73 .\" commit 269f21344b23e552c21c9e2d7ca258479dcd7a0a
  74 Set the close-on-exec flag for the message queue descriptor.
  75 See
  76 .BR open (2)
  77 for a discussion of why this flag is useful.
  78 .TP
  79 .B O_CREAT
  80 Create the message queue if it does not exist.
  81 The owner (user ID) of the message queue is set to the effective
  82 user ID of the calling process.
  83 The group ownership (group ID) is set to the effective group ID
  84 of the calling process.
  85 .\" In reality the filesystem IDs are used on Linux.
  86 .TP
  87 .B O_EXCL
  88 If
  89 .B O_CREAT
  90 was specified in
  91 .IR oflag ,
  92 and a queue with the given
  93 .I name
  94 already exists, then fail with the error
  95 .BR EEXIST .
  96 .TP
  97 .B O_NONBLOCK
  98 Open the queue in nonblocking mode.
  99 In circumstances where
 100 .BR mq_receive (3)
 101 and
 102 .BR mq_send (3)
 103 would normally block, these functions instead fail with the error
 104 .BR EAGAIN .
 105 .PP
 106 If
 107 .B O_CREAT
 108 is specified in
 109 .IR oflag ,
 110 then two additional arguments must be supplied.
 111 The
 112 .I mode
 113 argument specifies the permissions to be placed on the new queue,
 114 as for
 115 .BR open (2).
 116 (Symbolic definitions for the permissions bits can be obtained by including
 117 .IR <sys/stat.h> .)
 118 The permissions settings are masked against the process umask.
 119 .PP
 120 The fields of the
 121 .IR "struct mq_attr"
 122 pointed to
 123 .I attr
 124 specify the maximum number of messages and
 125 the maximum size of messages that the queue will allow.
 126 This structure is defined as follows:
 127 .PP
 128 .in +4n
 129 .EX
 130 struct mq_attr {
 131     long mq_flags;       /* Flags (ignored for mq_open()) */
 132     long mq_maxmsg;      /* Max. # of messages on queue */
 133     long mq_msgsize;     /* Max. message size (bytes) */
 134     long mq_curmsgs;     /* # of messages currently in queue
 135                             (ignored for mq_open()) */
 136 };
 137 .EE
 138 .in
 139 .PP
 140 Only the
 141 .I mq_maxmsg
 142 and
 143 .I mq_msgsize
 144 fields are employed when calling
 145 .BR mq_open ();
 146 the values in the remaining fields are ignored.
 147 .PP
 148 If
 149 .I attr
 150 is NULL, then the queue is created with implementation-defined
 151 default attributes.
 152 Since Linux 3.5, two
 153 .I /proc
 154 files can be used to control these defaults; see
 155 .BR mq_overview (7)
 156 for details.
 157 .SH RETURN VALUE
 158 On success,
 159 .BR mq_open ()
 160 returns a message queue descriptor for use by other
 161 message queue functions.
 162 On error,
 163 .BR mq_open ()
 164 returns
 165 .IR "(mqd_t)\ \-1",
 166 with
 167 .I errno
 168 set to indicate the error.
 169 .SH ERRORS
 170 .TP
 171 .B EACCES
 172 The queue exists, but the caller does not have permission to
 173 open it in the specified mode.
 174 .TP
 175 .B EACCES
 176 .I name
 177 contained more than one slash.
 178 .\" Note that this isn't consistent with the same case for sem_open()
 179 .TP
 180 .B EEXIST
 181 Both
 182 .B O_CREAT
 183 and
 184 .B O_EXCL
 185 were specified in
 186 .IR oflag ,
 187 but a queue with this
 188 .I name
 189 already exists.
 190 .TP
 191 .B EINVAL
 192 .\" glibc checks whether the name starts with a "/" and if not,
 193 .\" gives this error
 194 .I name
 195 doesn't follow the format in
 196 .BR mq_overview (7).
 197 .TP
 198 .B EINVAL
 199 .B O_CREAT
 200 was specified in
 201 .IR oflag ,
 202 and
 203 .I attr
 204 was not NULL, but
 205 .I attr\->mq_maxmsg
 206 or
 207 .I attr\->mq_msqsize
 208 was invalid.
 209 Both of these fields must be greater than zero.
 210 In a process that is unprivileged (does not have the
 211 .B CAP_SYS_RESOURCE
 212 capability),
 213 .I attr\->mq_maxmsg
 214 must be less than or equal to the
 215 .I msg_max
 216 limit, and
 217 .I attr\->mq_msgsize
 218 must be less than or equal to the
 219 .I msgsize_max
 220 limit.
 221 In addition, even in a privileged process,
 222 .I attr\->mq_maxmsg
 223 cannot exceed the
 224 .B HARD_MAX
 225 limit.
 226 (See
 227 .BR mq_overview (7)
 228 for details of these limits.)
 229 .TP
 230 .B EMFILE
 231 The per-process limit on the number of open file
 232 and message queue descriptors has been reached
 233 (see the description of
 234 .BR RLIMIT_NOFILE
 235 in
 236 .BR getrlimit (2)).
 237 .TP
 238 .B ENAMETOOLONG
 239 .I name
 240 was too long.
 241 .TP
 242 .B ENFILE
 243 The system-wide limit on the total number of open files
 244 and message queues has been reached.
 245 .TP
 246 .B ENOENT
 247 The
 248 .B O_CREAT
 249 flag was not specified in
 250 .IR oflag ,
 251 and no queue with this
 252 .I name
 253 exists.
 254 .TP
 255 .B ENOENT
 256 .I name
 257 was just "/" followed by no other characters.
 258 .\" Note that this isn't consistent with the same case for sem_open()
 259 .TP
 260 .B ENOMEM
 261 Insufficient memory.
 262 .TP
 263 .B ENOSPC
 264 Insufficient space for the creation of a new message queue.
 265 This probably occurred because the
 266 .I queues_max
 267 limit was encountered; see
 268 .BR mq_overview (7).
 269 .SH ATTRIBUTES
 270 For an explanation of the terms used in this section, see
 271 .BR attributes (7).
 272 .ad l
 273 .nh
 274 .TS
 275 allbox;
 276 lbx lb lb
 277 l l l.
 278 Interface       Attribute       Value
 279 T{
 280 .BR mq_open ()
 281 T}      Thread safety   MT-Safe
 282 .TE
 283 .hy
 284 .ad
 285 .sp 1
 286 .SH CONFORMING TO
 287 POSIX.1-2001, POSIX.1-2008.
 288 .SH NOTES
 289 .SS C library/kernel differences
 290 The
 291 .BR mq_open ()
 292 library function is implemented on top of a system call of the same name.
 293 The library function performs the check that the
 294 .I name
 295 starts with a slash (/), giving the
 296 .B EINVAL
 297 error if it does not.
 298 The kernel system call expects
 299 .I name
 300 to contain no preceding slash,
 301 so the C library function passes
 302 .I name
 303 without the preceding slash (i.e.,
 304 .IR name+1 )
 305 to the system call.
 306 .SH BUGS
 307 In kernels before 2.6.14,
 308 the process umask was not applied to the permissions specified in
 309 .IR mode .
 310 .SH SEE ALSO
 311 .BR mq_close (3),
 312 .BR mq_getattr (3),
 313 .BR mq_notify (3),
 314 .BR mq_receive (3),
 315 .BR mq_send (3),
 316 .BR mq_unlink (3),
 317 .BR mq_overview (7)