original/man3/mq_open.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_OPEN 3 2014-10-02 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 mq_open \- open a message queue
  29 .SH SYNOPSIS
  30 .nf
  31 .BR "#include <fcntl.h>" "           /* For O_* constants */"
  32 .BR "#include <sys/stat.h>" "        /* For mode constants */"
  33 .B #include <mqueue.h>
  34 .sp
  35 .BI "mqd_t mq_open(const char *" name ", int " oflag );
  36 .BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode ,
  37 .BI "              struct mq_attr *" attr );
  38 .fi
  39 .sp
  40 Link with \fI\-lrt\fP.
  41 .SH DESCRIPTION
  42 .BR mq_open ()
  43 creates a new POSIX message queue or opens an existing queue.
  44 The queue is identified by
  45 .IR name .
  46 For details of the construction of
  47 .IR name ,
  48 see
  49 .BR mq_overview (7).
  50
  51 The
  52 .I oflag
  53 argument specifies flags that control the operation of the call.
  54 (Definitions of the flags values can be obtained by including
  55 .IR <fcntl.h> .)
  56 Exactly one of the following must be specified in
  57 .IR oflag :
  58 .TP
  59 .B O_RDONLY
  60 Open the queue to receive messages only.
  61 .TP
  62 .B O_WRONLY
  63 Open the queue to send messages only.
  64 .TP
  65 .B O_RDWR
  66 Open the queue to both send and receive messages.
  67 .PP
  68 Zero or more of the following flags can additionally be
  69 .IR OR ed
  70 in
  71 .IR oflag :
  72 .TP
  73 .B O_NONBLOCK
  74 Open the queue in nonblocking mode.
  75 In circumstances where
  76 .BR mq_receive (3)
  77 and
  78 .BR mq_send (3)
  79 would normally block, these functions instead fail with the error
  80 .BR EAGAIN .
  81 .TP
  82 .B O_CREAT
  83 Create the message queue if it does not exist.
  84 The owner (user ID) of the message queue is set to the effective
  85 user ID of the calling process.
  86 The group ownership (group ID) is set to the effective group ID
  87 of the calling process.
  88 .\" In reality the filesystem IDs are used on Linux.
  89 .TP
  90 .B O_EXCL
  91 If
  92 .B O_CREAT
  93 was specified in
  94 .IR oflag ,
  95 and a queue with the given
  96 .I name
  97 already exists, then fail with the error
  98 .BR EEXIST .
  99 .PP
 100 If
 101 .B O_CREAT
 102 is specified in
 103 .IR oflag ,
 104 then two additional arguments must be supplied.
 105 The
 106 .I mode
 107 argument specifies the permissions to be placed on the new queue,
 108 as for
 109 .BR open (2).
 110 (Symbolic definitions for the permissions bits can be obtained by including
 111 .IR <sys/stat.h> .)
 112 The permissions settings are masked against the process umask.
 113
 114 The
 115 .I attr
 116 argument specifies attributes for the queue.
 117 See
 118 .BR mq_getattr (3)
 119 for details.
 120 If
 121 .I attr
 122 is NULL, then the queue is created with implementation-defined
 123 default attributes.
 124 Since Linux 3.5, two
 125 .I /proc
 126 files can be used to control these defaults; see
 127 .BR mq_overview (7)
 128 for details.
 129 .SH RETURN VALUE
 130 On success,
 131 .BR mq_open ()
 132 returns a message queue descriptor for use by other
 133 message queue functions.
 134 On error,
 135 .BR mq_open ()
 136 returns
 137 .IR "(mqd_t)\ \-1",
 138 with
 139 .I errno
 140 set to indicate the error.
 141 .SH ERRORS
 142 .TP
 143 .B EACCES
 144 The queue exists, but the caller does not have permission to
 145 open it in the specified mode.
 146 .TP
 147 .B EACCES
 148 .I name
 149 contained more than one slash.
 150 .\" Note that this isn't consistent with the same case for sem_open()
 151 .TP
 152 .B EEXIST
 153 Both
 154 .B O_CREAT
 155 and
 156 .B O_EXCL
 157 were specified in
 158 .IR oflag ,
 159 but a queue with this
 160 .I name
 161 already exists.
 162 .TP
 163 .B EINVAL
 164 .B O_CREAT
 165 was specified in
 166 .IR oflag ,
 167 and
 168 .I attr
 169 was not NULL, but
 170 .I attr\->mq_maxmsg
 171 or
 172 .I attr\->mq_msqsize
 173 was invalid.
 174 Both of these fields must be greater than zero.
 175 In a process that is unprivileged (does not have the
 176 .B CAP_SYS_RESOURCE
 177 capability),
 178 .I attr\->mq_maxmsg
 179 must be less than or equal to the
 180 .I msg_max
 181 limit, and
 182 .I attr\->mq_msgsize
 183 must be less than or equal to the
 184 .I msgsize_max
 185 limit.
 186 In addition, even in a privileged process,
 187 .I attr\->mq_maxmsg
 188 cannot exceed the
 189 .B HARD_MAX
 190 limit.
 191 (See
 192 .BR mq_overview (7)
 193 for details of these limits.)
 194 .TP
 195 .B EMFILE
 196 The process already has the maximum number of files and
 197 message queues open.
 198 .TP
 199 .B ENAMETOOLONG
 200 .I name
 201 was too long.
 202 .TP
 203 .B ENFILE
 204 The system limit on the total number of open files and message queues
 205 has been reached.
 206 .TP
 207 .B ENOENT
 208 The
 209 .B O_CREAT
 210 flag was not specified in
 211 .IR oflag ,
 212 and no queue with this
 213 .I name
 214 exists.
 215 .TP
 216 .B ENOENT
 217 .I name
 218 was just "/" followed by no other characters.
 219 .\" Note that this isn't consistent with the same case for sem_open()
 220 .TP
 221 .B ENOMEM
 222 Insufficient memory.
 223 .TP
 224 .B ENOSPC
 225 Insufficient space for the creation of a new message queue.
 226 This probably occurred because the
 227 .I queues_max
 228 limit was encountered; see
 229 .BR mq_overview (7).
 230 .SH ATTRIBUTES
 231 .SS Multithreading (see pthreads(7))
 232 The
 233 .BR mq_open ()
 234 function is thread-safe.
 235 .SH CONFORMING TO
 236 POSIX.1-2001.
 237 .SH BUGS
 238 In kernels before 2.6.14,
 239 the process umask was not applied to the permissions specified in
 240 .IR mode .
 241 .SH SEE ALSO
 242 .BR mq_close (3),
 243 .BR mq_getattr (3),
 244 .BR mq_notify (3),
 245 .BR mq_receive (3),
 246 .BR mq_send (3),
 247 .BR mq_unlink (3),
 248 .BR mq_overview (7)
 249 .SH COLOPHON
 250 This page is part of release 3.75 of the Linux
 251 .I man-pages
 252 project.
 253 A description of the project,
 254 information about reporting bugs,
 255 and the latest version of this page,
 256 can be found at
 257 \%http://www.kernel.org/doc/man\-pages/.