man3/mq_open.3

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