470 lines
9.9 KiB
HTML
470 lines
9.9 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of MQ_OPEN</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>MQ_OPEN</H1>
|
|
Section: Linux Programmer's Manual (3)<BR>Updated: 2017-09-15<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
mq_open - open a message queue
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/fcntl.h">fcntl.h</A>></B> /* For O_* constants */
|
|
<B>#include <<A HREF="file:///usr/include/sys/stat.h">sys/stat.h</A>></B> /* For mode constants */
|
|
<B>#include <<A HREF="file:///usr/include/mqueue.h">mqueue.h</A>></B>
|
|
|
|
<B>mqd_t mq_open(const char *</B><I>name</I><B>, int </B><I>oflag</I><B>);</B>
|
|
<B>mqd_t mq_open(const char *</B><I>name</I><B>, int </B><I>oflag</I><B>, mode_t </B><I>mode</I><B>,</B>
|
|
<B> struct mq_attr *</B><I>attr</I><B>);</B>
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
Link with <I>-lrt</I>.
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>mq_open</B>()
|
|
|
|
creates a new POSIX message queue or opens an existing queue.
|
|
The queue is identified by
|
|
<I>name</I>.
|
|
|
|
For details of the construction of
|
|
<I>name</I>,
|
|
|
|
see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+mq_overview">mq_overview</A></B>(7).
|
|
|
|
<P>
|
|
|
|
The
|
|
<I>oflag</I>
|
|
|
|
argument specifies flags that control the operation of the call.
|
|
(Definitions of the flags values can be obtained by including
|
|
<I><<A HREF="file:///usr/include/fcntl.h">fcntl.h</A>></I>.)
|
|
|
|
Exactly one of the following must be specified in
|
|
<I>oflag</I>:
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>O_RDONLY</B>
|
|
|
|
<DD>
|
|
Open the queue to receive messages only.
|
|
<DT id="2"><B>O_WRONLY</B>
|
|
|
|
<DD>
|
|
Open the queue to send messages only.
|
|
<DT id="3"><B>O_RDWR</B>
|
|
|
|
<DD>
|
|
Open the queue to both send and receive messages.
|
|
</DL>
|
|
<P>
|
|
|
|
Zero or more of the following flags can additionally be
|
|
<I>OR</I>ed
|
|
|
|
in
|
|
<I>oflag</I>:
|
|
|
|
<DL COMPACT>
|
|
<DT id="4"><B>O_CLOEXEC</B> (since Linux 2.6.26)
|
|
|
|
<DD>
|
|
|
|
Set the close-on-exec flag for the message queue descriptor.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2)
|
|
|
|
for a discussion of why this flag is useful.
|
|
<DT id="5"><B>O_CREAT</B>
|
|
|
|
<DD>
|
|
Create the message queue if it does not exist.
|
|
The owner (user ID) of the message queue is set to the effective
|
|
user ID of the calling process.
|
|
The group ownership (group ID) is set to the effective group ID
|
|
of the calling process.
|
|
|
|
<DT id="6"><B>O_EXCL</B>
|
|
|
|
<DD>
|
|
If
|
|
<B>O_CREAT</B>
|
|
|
|
was specified in
|
|
<I>oflag</I>,
|
|
|
|
and a queue with the given
|
|
<I>name</I>
|
|
|
|
already exists, then fail with the error
|
|
<B>EEXIST</B>.
|
|
|
|
<DT id="7"><B>O_NONBLOCK</B>
|
|
|
|
<DD>
|
|
Open the queue in nonblocking mode.
|
|
In circumstances where
|
|
<B><A HREF="/cgi-bin/man/man2html?3+mq_receive">mq_receive</A></B>(3)
|
|
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?3+mq_send">mq_send</A></B>(3)
|
|
|
|
would normally block, these functions instead fail with the error
|
|
<B>EAGAIN</B>.
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
If
|
|
<B>O_CREAT</B>
|
|
|
|
is specified in
|
|
<I>oflag</I>,
|
|
|
|
then two additional arguments must be supplied.
|
|
The
|
|
<I>mode</I>
|
|
|
|
argument specifies the permissions to be placed on the new queue,
|
|
as for
|
|
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2).
|
|
|
|
(Symbolic definitions for the permissions bits can be obtained by including
|
|
<I><<A HREF="file:///usr/include/sys/stat.h">sys/stat.h</A>></I>.)
|
|
|
|
The permissions settings are masked against the process umask.
|
|
<P>
|
|
|
|
The fields of the
|
|
<I>struct mq_attr</I>
|
|
|
|
pointed to
|
|
<I>attr</I>
|
|
|
|
specify the maximum number of messages and
|
|
the maximum size of messages that the queue will allow.
|
|
This structure is defined as follows:
|
|
<P>
|
|
|
|
<P>
|
|
|
|
|
|
|
|
struct mq_attr {
|
|
<BR> long mq_flags; /* Flags (ignored for mq_open()) */
|
|
<BR> long mq_maxmsg; /* Max. # of messages on queue */
|
|
<BR> long mq_msgsize; /* Max. message size (bytes) */
|
|
<BR> long mq_curmsgs; /* # of messages currently in queue
|
|
<BR> (ignored for mq_open()) */
|
|
};
|
|
|
|
|
|
<P>
|
|
|
|
Only the
|
|
<I>mq_maxmsg</I>
|
|
|
|
and
|
|
<I>mq_msgsize</I>
|
|
|
|
fields are employed when calling
|
|
<B>mq_open</B>();
|
|
|
|
the values in the remaining fields are ignored.
|
|
<P>
|
|
|
|
If
|
|
<I>attr</I>
|
|
|
|
is NULL, then the queue is created with implementation-defined
|
|
default attributes.
|
|
Since Linux 3.5, two
|
|
<I>/proc</I>
|
|
|
|
files can be used to control these defaults; see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+mq_overview">mq_overview</A></B>(7)
|
|
|
|
for details.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
On success,
|
|
<B>mq_open</B>()
|
|
|
|
returns a message queue descriptor for use by other
|
|
message queue functions.
|
|
On error,
|
|
<B>mq_open</B>()
|
|
|
|
returns
|
|
<I>(mqd_t) -1,</I>
|
|
|
|
with
|
|
<I>errno</I>
|
|
|
|
set to indicate the error.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="8"><B>EACCES</B>
|
|
|
|
<DD>
|
|
The queue exists, but the caller does not have permission to
|
|
open it in the specified mode.
|
|
<DT id="9"><B>EACCES</B>
|
|
|
|
<DD>
|
|
<I>name</I>
|
|
|
|
contained more than one slash.
|
|
|
|
<DT id="10"><B>EEXIST</B>
|
|
|
|
<DD>
|
|
Both
|
|
<B>O_CREAT</B>
|
|
|
|
and
|
|
<B>O_EXCL</B>
|
|
|
|
were specified in
|
|
<I>oflag</I>,
|
|
|
|
but a queue with this
|
|
<I>name</I>
|
|
|
|
already exists.
|
|
<DT id="11"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
|
|
|
|
<I>name</I>
|
|
|
|
doesn't follow the format in
|
|
<B><A HREF="/cgi-bin/man/man2html?7+mq_overview">mq_overview</A></B>(7).
|
|
|
|
<DT id="12"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<B>O_CREAT</B>
|
|
|
|
was specified in
|
|
<I>oflag</I>,
|
|
|
|
and
|
|
<I>attr</I>
|
|
|
|
was not NULL, but
|
|
<I>attr->mq_maxmsg</I>
|
|
|
|
or
|
|
<I>attr->mq_msqsize</I>
|
|
|
|
was invalid.
|
|
Both of these fields must be greater than zero.
|
|
In a process that is unprivileged (does not have the
|
|
<B>CAP_SYS_RESOURCE</B>
|
|
|
|
capability),
|
|
<I>attr->mq_maxmsg</I>
|
|
|
|
must be less than or equal to the
|
|
<I>msg_max</I>
|
|
|
|
limit, and
|
|
<I>attr->mq_msgsize</I>
|
|
|
|
must be less than or equal to the
|
|
<I>msgsize_max</I>
|
|
|
|
limit.
|
|
In addition, even in a privileged process,
|
|
<I>attr->mq_maxmsg</I>
|
|
|
|
cannot exceed the
|
|
<B>HARD_MAX</B>
|
|
|
|
limit.
|
|
(See
|
|
<B><A HREF="/cgi-bin/man/man2html?7+mq_overview">mq_overview</A></B>(7)
|
|
|
|
for details of these limits.)
|
|
<DT id="13"><B>EMFILE</B>
|
|
|
|
<DD>
|
|
The per-process limit on the number of open file
|
|
and message queue descriptors has been reached
|
|
(see the description of
|
|
<B>RLIMIT_NOFILE</B>
|
|
|
|
in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+getrlimit">getrlimit</A></B>(2)).
|
|
|
|
<DT id="14"><B>ENAMETOOLONG</B>
|
|
|
|
<DD>
|
|
<I>name</I>
|
|
|
|
was too long.
|
|
<DT id="15"><B>ENFILE</B>
|
|
|
|
<DD>
|
|
The system-wide limit on the total number of open files
|
|
and message queues has been reached.
|
|
<DT id="16"><B>ENOENT</B>
|
|
|
|
<DD>
|
|
The
|
|
<B>O_CREAT</B>
|
|
|
|
flag was not specified in
|
|
<I>oflag</I>,
|
|
|
|
and no queue with this
|
|
<I>name</I>
|
|
|
|
exists.
|
|
<DT id="17"><B>ENOENT</B>
|
|
|
|
<DD>
|
|
<I>name</I>
|
|
|
|
was just "/" followed by no other characters.
|
|
|
|
<DT id="18"><B>ENOMEM</B>
|
|
|
|
<DD>
|
|
Insufficient memory.
|
|
<DT id="19"><B>ENOSPC</B>
|
|
|
|
<DD>
|
|
Insufficient space for the creation of a new message queue.
|
|
This probably occurred because the
|
|
<I>queues_max</I>
|
|
|
|
limit was encountered; see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+mq_overview">mq_overview</A></B>(7).
|
|
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>ATTRIBUTES</H2>
|
|
|
|
For an explanation of the terms used in this section, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+attributes">attributes</A></B>(7).
|
|
|
|
<TABLE BORDER>
|
|
<TR VALIGN=top><TD><B>Interface</B></TD><TD><B>Attribute</B></TD><TD><B>Value</B><BR></TD></TR>
|
|
<TR VALIGN=top><TD>
|
|
<B>mq_open</B>()
|
|
|
|
</TD><TD>Thread safety</TD><TD>MT-Safe<BR></TD></TR>
|
|
</TABLE>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
POSIX.1-2001, POSIX.1-2008.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>C library/kernel differences</H3>
|
|
|
|
The
|
|
<B>mq_open</B>()
|
|
|
|
library function is implemented on top of a system call of the same name.
|
|
The library function performs the check that the
|
|
<I>name</I>
|
|
|
|
starts with a slash (/), giving the
|
|
<B>EINVAL</B>
|
|
|
|
error if it does not.
|
|
The kernel system call expects
|
|
<I>name</I>
|
|
|
|
to contain no preceding slash,
|
|
so the C library function passes
|
|
<I>name</I>
|
|
|
|
without the preceding slash (i.e.,
|
|
<I>name+1</I>)
|
|
|
|
to the system call.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
In kernels before 2.6.14,
|
|
the process umask was not applied to the permissions specified in
|
|
<I>mode</I>.
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+mq_close">mq_close</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+mq_getattr">mq_getattr</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+mq_notify">mq_notify</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+mq_receive">mq_receive</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+mq_send">mq_send</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?3+mq_unlink">mq_unlink</A></B>(3),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+mq_overview">mq_overview</A></B>(7)
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="20"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="21"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="22"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="23"><A HREF="#lbAE">RETURN VALUE</A><DD>
|
|
<DT id="24"><A HREF="#lbAF">ERRORS</A><DD>
|
|
<DT id="25"><A HREF="#lbAG">ATTRIBUTES</A><DD>
|
|
<DT id="26"><A HREF="#lbAH">CONFORMING TO</A><DD>
|
|
<DT id="27"><A HREF="#lbAI">NOTES</A><DD>
|
|
<DL>
|
|
<DT id="28"><A HREF="#lbAJ">C library/kernel differences</A><DD>
|
|
</DL>
|
|
<DT id="29"><A HREF="#lbAK">BUGS</A><DD>
|
|
<DT id="30"><A HREF="#lbAL">SEE ALSO</A><DD>
|
|
<DT id="31"><A HREF="#lbAM">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:48 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|