1mq_open(3)                 Library Functions Manual                 mq_open(3)
2
3
4

NAME

6       mq_open - open a message queue
7

LIBRARY

9       Real-time library (librt, -lrt)
10

SYNOPSIS

12       #include <fcntl.h>           /* For O_* constants */
13       #include <sys/stat.h>        /* For mode constants */
14       #include <mqueue.h>
15
16       mqd_t mq_open(const char *name, int oflag);
17       mqd_t mq_open(const char *name, int oflag, mode_t mode,
18                     struct mq_attr *attr);
19

DESCRIPTION

21       mq_open() creates a new POSIX message queue or opens an existing queue.
22       The queue is identified by name.  For details of  the  construction  of
23       name, see mq_overview(7).
24
25       The  oflag  argument  specifies flags that control the operation of the
26       call.  (Definitions of the flags values can be  obtained  by  including
27       <fcntl.h>.)  Exactly one of the following must be specified in oflag:
28
29       O_RDONLY
30              Open the queue to receive messages only.
31
32       O_WRONLY
33              Open the queue to send messages only.
34
35       O_RDWR Open the queue to both send and receive messages.
36
37       Zero or more of the following flags can additionally be ORed in oflag:
38
39       O_CLOEXEC (since Linux 2.6.26)
40              Set  the  close-on-exec  flag  for the message queue descriptor.
41              See open(2) for a discussion of why this flag is useful.
42
43       O_CREAT
44              Create the message queue if it does not exist.  The owner  (user
45              ID)  of the message queue is set to the effective user ID of the
46              calling process.  The group ownership (group ID) is set  to  the
47              effective group ID of the calling process.
48
49       O_EXCL If  O_CREAT  was  specified in oflag, and a queue with the given
50              name already exists, then fail with the error EEXIST.
51
52       O_NONBLOCK
53              Open the queue in  nonblocking  mode.   In  circumstances  where
54              mq_receive(3)  and  mq_send(3) would normally block, these func‐
55              tions instead fail with the error EAGAIN.
56
57       If O_CREAT is specified in oflag, then two additional arguments must be
58       supplied.   The mode argument specifies the permissions to be placed on
59       the new queue, as for open(2).  (Symbolic definitions for  the  permis‐
60       sions bits can be obtained by including <sys/stat.h>.)  The permissions
61       settings are masked against the process umask.
62
63       The fields of the struct mq_attr pointed to attr  specify  the  maximum
64       number of messages and the maximum size of messages that the queue will
65       allow.  This structure is defined as follows:
66
67           struct mq_attr {
68               long mq_flags;       /* Flags (ignored for mq_open()) */
69               long mq_maxmsg;      /* Max. # of messages on queue */
70               long mq_msgsize;     /* Max. message size (bytes) */
71               long mq_curmsgs;     /* # of messages currently in queue
72                                       (ignored for mq_open()) */
73           };
74
75       Only the mq_maxmsg and mq_msgsize  fields  are  employed  when  calling
76       mq_open(); the values in the remaining fields are ignored.
77
78       If  attr is NULL, then the queue is created with implementation-defined
79       default attributes.  Since Linux 3.5, two /proc files can  be  used  to
80       control these defaults; see mq_overview(7) for details.
81

RETURN VALUE

83       On  success,  mq_open()  returns  a message queue descriptor for use by
84       other message queue functions.  On error, mq_open() returns (mqd_t) -1,
85       with errno set to indicate the error.
86

ERRORS

88       EACCES The  queue  exists,  but  the caller does not have permission to
89              open it in the specified mode.
90
91       EACCES name contained more than one slash.
92
93       EEXIST Both O_CREAT and O_EXCL were specified in  oflag,  but  a  queue
94              with this name already exists.
95
96       EINVAL name doesn't follow the format in mq_overview(7).
97
98       EINVAL O_CREAT  was  specified  in  oflag,  and  attr was not NULL, but
99              attr->mq_maxmsg or attr->mq_msqsize was invalid.  Both of  these
100              fields must be greater than zero.  In a process that is unprivi‐
101              leged  (does  not   have   the   CAP_SYS_RESOURCE   capability),
102              attr->mq_maxmsg must be less than or equal to the msg_max limit,
103              and attr->mq_msgsize must be less than  or  equal  to  the  msg‐
104              size_max  limit.   In  addition,  even  in a privileged process,
105              attr->mq_maxmsg cannot exceed the HARD_MAX limit.  (See mq_over‐
106              view(7) for details of these limits.)
107
108       EMFILE The  per-process  limit  on  the number of open file and message
109              queue descriptors has  been  reached  (see  the  description  of
110              RLIMIT_NOFILE in getrlimit(2)).
111
112       ENAMETOOLONG
113              name was too long.
114
115       ENFILE The system-wide limit on the total number of open files and mes‐
116              sage queues has been reached.
117
118       ENOENT The O_CREAT flag was not specified in oflag, and no  queue  with
119              this name exists.
120
121       ENOENT name was just "/" followed by no other characters.
122
123       ENOMEM Insufficient memory.
124
125       ENOSPC Insufficient  space  for  the  creation  of a new message queue.
126              This probably occurred because the queues_max limit was  encoun‐
127              tered; see mq_overview(7).
128

ATTRIBUTES

130       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
131       tributes(7).
132
133       ┌────────────────────────────────────────────┬───────────────┬─────────┐
134Interface                                   Attribute     Value   
135       ├────────────────────────────────────────────┼───────────────┼─────────┤
136mq_open()                                   │ Thread safety │ MT-Safe │
137       └────────────────────────────────────────────┴───────────────┴─────────┘
138

VERSIONS

140   C library/kernel differences
141       The mq_open() library function is implemented on top of a  system  call
142       of  the  same  name.   The library function performs the check that the
143       name starts with a slash (/), giving the EINVAL error if it  does  not.
144       The  kernel  system call expects name to contain no preceding slash, so
145       the C library function passes name without the preceding  slash  (i.e.,
146       name+1) to the system call.
147

STANDARDS

149       POSIX.1-2008.
150

HISTORY

152       POSIX.1-2001.
153

BUGS

155       Before  Linux  2.6.14, the process umask was not applied to the permis‐
156       sions specified in mode.
157

SEE ALSO

159       mq_close(3), mq_getattr(3),  mq_notify(3),  mq_receive(3),  mq_send(3),
160       mq_unlink(3), mq_overview(7)
161
162
163
164Linux man-pages 6.04              2023-03-30                        mq_open(3)
Impressum