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 2009-02-20 "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 The
 114 .I attr
 115 argument specifies attributes for the queue.
 116 See
 117 .BR mq_getattr (3)
 118 for details.
 119 If
 120 .I attr
 121 is NULL, then the queue is created with implementation-defined
 122 default attributes.
 123 .SH RETURN VALUE
 124 On success,
 125 .BR mq_open ()
 126 returns a message queue descriptor for use by other
 127 message queue functions.
 128 On error,
 129 .BR mq_open ()
 130 returns
 131 .IR "(mqd_t)\ \-1",
 132 with
 133 .I errno
 134 set to indicate the error.
 135 .SH ERRORS
 136 .TP
 137 .B EACCES
 138 The queue exists, but the caller does not have permission to
 139 open it in the specified mode.
 140 .TP
 141 .B EACCES
 142 .I name
 143 contained more than one slash.
 144 .\" Note that this isn't consistent with the same case for sem_open()
 145 .TP
 146 .B EEXIST
 147 Both
 148 .B O_CREAT
 149 and
 150 .B O_EXCL
 151 were specified in
 152 .IR oflag ,
 153 but a queue with this
 154 .I name
 155 already exists.
 156 .TP
 157 .B EINVAL
 158 .B O_CREAT
 159 was specified in
 160 .IR oflag ,
 161 and
 162 .I attr
 163 was not NULL, but
 164 .I attr\->mq_maxmsg
 165 or
 166 .I attr\->mq_msqsize
 167 was invalid.
 168 Both of these fields must be greater than zero.
 169 In a process that is unprivileged (does not have the
 170 .B CAP_SYS_RESOURCE
 171 capability),
 172 .I attr\->mq_maxmsg
 173 must be less than or equal to the
 174 .I msg_max
 175 limit, and
 176 .I attr\->mq_msgsize
 177 must be less than or equal to the
 178 .I msgsize_max
 179 limit.
 180 In addition, even in a privileged process,
 181 .I attr\->mq_maxmsg
 182 cannot exceed the
 183 .B HARD_MAX
 184 limit.
 185 (See
 186 .BR mq_overview (7)
 187 for details of these limits.)
 188 .TP
 189 .B EMFILE
 190 The process already has the maximum number of files and
 191 message queues open.
 192 .TP
 193 .B ENAMETOOLONG
 194 .I name
 195 was too long.
 196 .TP
 197 .B ENFILE
 198 The system limit on the total number of open files and message queues
 199 has been reached.
 200 .TP
 201 .B ENOENT
 202 The
 203 .B O_CREAT
 204 flag was not specified in
 205 .IR oflag ,
 206 and no queue with this
 207 .I name
 208 exists.
 209 .TP
 210 .B ENOENT
 211 .I name
 212 was just "/" followed by no other characters.
 213 .\" Note that this isn't consistent with the same case for sem_open()
 214 .TP
 215 .B ENOMEM
 216 Insufficient memory.
 217 .TP
 218 .B ENOSPC
 219 Insufficient space for the creation of a new message queue.
 220 This probably occurred because the
 221 .I queues_max
 222 limit was encountered; see
 223 .BR mq_overview (7).
 224 .SH CONFORMING TO
 225 POSIX.1-2001.
 226 .SH BUGS
 227 In kernels before 2.6.14,
 228 the process umask was not applied to the permissions specified in
 229 .IR mode .
 230 .SH SEE ALSO
 231 .BR mq_close (3),
 232 .BR mq_getattr (3),
 233 .BR mq_notify (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.67 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/.