1 files changed, 298 insertions, 0 deletions
diff --git a/man/man3/mq_open.3 b/man/man3/mq_open.3
new file mode 100644
index 000000000..7343ea093
--- /dev/null
+++ b/man/man3/mq_open.3
@@ -0,0 +1,298 @@
+'\" t
+.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH mq_open 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+mq_open \- open a message queue
+.SH LIBRARY
+Real-time library
+.RI ( librt ", " \-lrt )
+.SH SYNOPSIS
+.nf
+.BR "#include <fcntl.h>" "           /* For O_* constants */"
+.BR "#include <sys/stat.h>" "        /* For mode constants */"
+.B #include <mqueue.h>
+.P
+.BI "mqd_t mq_open(const char *" name ", int " oflag );
+.BI "mqd_t mq_open(const char *" name ", int " oflag ", mode_t " mode ,
+.BI "              struct mq_attr *" attr );
+.fi
+.SH DESCRIPTION
+.BR mq_open ()
+creates a new POSIX message queue or opens an existing queue.
+The queue is identified by
+.IR name .
+For details of the construction of
+.IR name ,
+see
+.BR mq_overview (7).
+.P
+The
+.I oflag
+argument specifies flags that control the operation of the call.
+(Definitions of the flags values can be obtained by including
+.IR <fcntl.h> .)
+Exactly one of the following must be specified in
+.IR oflag :
+.TP
+.B O_RDONLY
+Open the queue to receive messages only.
+.TP
+.B O_WRONLY
+Open the queue to send messages only.
+.TP
+.B O_RDWR
+Open the queue to both send and receive messages.
+.P
+Zero or more of the following flags can additionally be
+.IR OR ed
+in
+.IR oflag :
+.TP
+.BR O_CLOEXEC " (since Linux 2.6.26)"
+.\" commit 269f21344b23e552c21c9e2d7ca258479dcd7a0a
+Set the close-on-exec flag for the message queue descriptor.
+See
+.BR open (2)
+for a discussion of why this flag is useful.
+.TP
+.B O_CREAT
+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.
+.\" In reality the filesystem IDs are used on Linux.
+.TP
+.B O_EXCL
+If
+.B O_CREAT
+was specified in
+.IR oflag ,
+and a queue with the given
+.I name
+already exists, then fail with the error
+.BR EEXIST .
+.TP
+.B O_NONBLOCK
+Open the queue in nonblocking mode.
+In circumstances where
+.BR mq_receive (3)
+and
+.BR mq_send (3)
+would normally block, these functions instead fail with the error
+.BR EAGAIN .
+.P
+If
+.B O_CREAT
+is specified in
+.IR oflag ,
+then two additional arguments must be supplied.
+The
+.I mode
+argument specifies the permissions to be placed on the new queue,
+as for
+.BR open (2).
+(Symbolic definitions for the permissions bits can be obtained by including
+.IR <sys/stat.h> .)
+The permissions settings are masked against the process umask.
+.P
+The fields of the
+.I struct mq_attr
+pointed to
+.I attr
+specify the maximum number of messages and
+the maximum size of messages that the queue will allow.
+This structure is defined as follows:
+.P
+.in +4n
+.EX
+struct mq_attr {
+    long mq_flags;       /* Flags (ignored for mq_open()) */
+    long mq_maxmsg;      /* Max. # of messages on queue */
+    long mq_msgsize;     /* Max. message size (bytes) */
+    long mq_curmsgs;     /* # of messages currently in queue
+                            (ignored for mq_open()) */
+};
+.EE
+.in
+.P
+Only the
+.I mq_maxmsg
+and
+.I mq_msgsize
+fields are employed when calling
+.BR mq_open ();
+the values in the remaining fields are ignored.
+.P
+If
+.I attr
+is NULL, then the queue is created with implementation-defined
+default attributes.
+Since Linux 3.5, two
+.I /proc
+files can be used to control these defaults; see
+.BR mq_overview (7)
+for details.
+.SH RETURN VALUE
+On success,
+.BR mq_open ()
+returns a message queue descriptor for use by other
+message queue functions.
+On error,
+.BR mq_open ()
+returns
+.IR "(mqd_t)\ \-1",
+with
+.I errno
+set to indicate the error.
+.SH ERRORS
+.TP
+.B EACCES
+The queue exists, but the caller does not have permission to
+open it in the specified mode.
+.TP
+.B EACCES
+.I name
+contained more than one slash.
+.\" Note that this isn't consistent with the same case for sem_open()
+.TP
+.B EEXIST
+Both
+.B O_CREAT
+and
+.B O_EXCL
+were specified in
+.IR oflag ,
+but a queue with this
+.I name
+already exists.
+.TP
+.B EINVAL
+.\" glibc checks whether the name starts with a "/" and if not,
+.\" gives this error
+.I name
+doesn't follow the format in
+.BR mq_overview (7).
+.TP
+.B EINVAL
+.B O_CREAT
+was specified in
+.IR oflag ,
+and
+.I attr
+was not NULL, but
+.I attr\->mq_maxmsg
+or
+.I attr\->mq_msqsize
+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
+capability),
+.I attr\->mq_maxmsg
+must be less than or equal to the
+.I msg_max
+limit, and
+.I attr\->mq_msgsize
+must be less than or equal to the
+.I msgsize_max
+limit.
+In addition, even in a privileged process,
+.I attr\->mq_maxmsg
+cannot exceed the
+.B HARD_MAX
+limit.
+(See
+.BR mq_overview (7)
+for details of these limits.)
+.TP
+.B EMFILE
+The per-process limit on the number of open file
+and message queue descriptors has been reached
+(see the description of
+.B RLIMIT_NOFILE
+in
+.BR getrlimit (2)).
+.TP
+.B ENAMETOOLONG
+.I name
+was too long.
+.TP
+.B ENFILE
+The system-wide limit on the total number of open files
+and message queues has been reached.
+.TP
+.B ENOENT
+The
+.B O_CREAT
+flag was not specified in
+.IR oflag ,
+and no queue with this
+.I name
+exists.
+.TP
+.B ENOENT
+.I name
+was just "/" followed by no other characters.
+.\" Note that this isn't consistent with the same case for sem_open()
+.TP
+.B ENOMEM
+Insufficient memory.
+.TP
+.B ENOSPC
+Insufficient space for the creation of a new message queue.
+This probably occurred because the
+.I queues_max
+limit was encountered; see
+.BR mq_overview (7).
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR mq_open ()
+T}	Thread safety	MT-Safe
+.TE
+.SH VERSIONS
+.SS C library/kernel differences
+The
+.BR mq_open ()
+library function is implemented on top of a system call of the same name.
+The library function performs the check that the
+.I name
+starts with a slash (/), giving the
+.B EINVAL
+error if it does not.
+The kernel system call expects
+.I name
+to contain no preceding slash,
+so the C library function passes
+.I name
+without the preceding slash (i.e.,
+.IR name+1 )
+to the system call.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH BUGS
+Before Linux 2.6.14,
+the process umask was not applied to the permissions specified in
+.IR mode .
+.SH SEE ALSO
+.BR mq_close (3),
+.BR mq_getattr (3),
+.BR mq_notify (3),
+.BR mq_receive (3),
+.BR mq_send (3),
+.BR mq_unlink (3),
+.BR mq_overview (7)