mirror of https://github.com/mkerrisk/man-pages
196 lines
7.5 KiB
Plaintext
196 lines
7.5 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "MQ_OPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" mq_open
|
||
|
.SH NAME
|
||
|
mq_open \- open a message queue (\fBREALTIME\fP)
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <mqueue.h>
|
||
|
.br
|
||
|
.sp
|
||
|
mqd_t mq_open(const char *\fP\fIname\fP\fB, int\fP \fIoflag\fP\fB,
|
||
|
\&...); \fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fImq_open\fP() function shall establish the connection between
|
||
|
a process and a message queue with a message queue
|
||
|
descriptor. It shall create an open message queue description that
|
||
|
refers to the message queue, and a message queue descriptor that
|
||
|
refers to that open message queue description. The message queue descriptor
|
||
|
is used by other functions to refer to that message
|
||
|
queue. The \fIname\fP argument points to a string naming a message
|
||
|
queue. It is unspecified whether the name appears in the file
|
||
|
system and is visible to other functions that take pathnames as arguments.
|
||
|
The \fIname\fP argument shall conform to the
|
||
|
construction rules for a pathname. If \fIname\fP begins with the slash
|
||
|
character, then processes calling \fImq_open\fP() with the
|
||
|
same value of \fIname\fP shall refer to the same message queue object,
|
||
|
as long as that name has not been removed. If \fIname\fP
|
||
|
does not begin with the slash character, the effect is implementation-defined.
|
||
|
The interpretation of slash characters other than
|
||
|
the leading slash character in \fIname\fP is implementation-defined.
|
||
|
If the \fIname\fP argument is not the name of an existing
|
||
|
message queue and creation is not requested, \fImq_open\fP() shall
|
||
|
fail and return an error.
|
||
|
.LP
|
||
|
A message queue descriptor may be implemented using a file descriptor,
|
||
|
in which case applications can open up to at least
|
||
|
{OPEN_MAX} file and message queues.
|
||
|
.LP
|
||
|
The \fIoflag\fP argument requests the desired receive and/or send
|
||
|
access to the message queue. The requested access permission
|
||
|
to receive messages or send messages shall be granted if the calling
|
||
|
process would be granted read or write access, respectively,
|
||
|
to an equivalently protected file.
|
||
|
.LP
|
||
|
The value of \fIoflag\fP is the bitwise-inclusive OR of values from
|
||
|
the following list. Applications shall specify exactly one
|
||
|
of the first three values (access modes) below in the value of \fIoflag\fP:
|
||
|
.TP 7
|
||
|
O_RDONLY
|
||
|
Open the message queue for receiving messages. The process can use
|
||
|
the returned message queue descriptor with \fImq_receive\fP(), but
|
||
|
not \fImq_send\fP(). A message
|
||
|
queue may be open multiple times in the same or different processes
|
||
|
for receiving messages.
|
||
|
.TP 7
|
||
|
O_WRONLY
|
||
|
Open the queue for sending messages. The process can use the returned
|
||
|
message queue descriptor with \fImq_send\fP() but not \fImq_receive\fP().
|
||
|
A message
|
||
|
queue may be open multiple times in the same or different processes
|
||
|
for sending messages.
|
||
|
.TP 7
|
||
|
O_RDWR
|
||
|
Open the queue for both receiving and sending messages. The process
|
||
|
can use any of the functions allowed for O_RDONLY and
|
||
|
O_WRONLY. A message queue may be open multiple times in the same or
|
||
|
different processes for sending messages.
|
||
|
.sp
|
||
|
.LP
|
||
|
Any combination of the remaining flags may be specified in the value
|
||
|
of \fIoflag\fP:
|
||
|
.TP 7
|
||
|
O_CREAT
|
||
|
Create a message queue. It requires two additional arguments: \fImode\fP,
|
||
|
which shall be of type \fBmode_t\fP, and
|
||
|
\fIattr\fP, which shall be a pointer to an \fBmq_attr\fP structure.
|
||
|
If the pathname \fIname\fP has already been used to create a
|
||
|
message queue that still exists, then this flag shall have no effect,
|
||
|
except as noted under O_EXCL. Otherwise, a message queue
|
||
|
shall be created without any messages in it. The user ID of the message
|
||
|
queue shall be set to the effective user ID of the process,
|
||
|
and the group ID of the message queue shall be set to the effective
|
||
|
group ID of the process. The file permission bits shall be set
|
||
|
to the value of \fImode\fP. When bits in \fImode\fP other than file
|
||
|
permission bits are set, the effect is
|
||
|
implementation-defined. If \fIattr\fP is NULL, the message queue shall
|
||
|
be created with implementation-defined default message
|
||
|
queue attributes. If \fIattr\fP is non-NULL and the calling process
|
||
|
has the appropriate privilege on \fIname\fP, the message
|
||
|
queue \fImq_maxmsg\fP and \fImq_msgsize\fP attributes shall be set
|
||
|
to the values of the corresponding members in the
|
||
|
\fBmq_attr\fP structure referred to by \fIattr\fP. If \fIattr\fP is
|
||
|
non-NULL, but the calling process does not have the
|
||
|
appropriate privilege on \fIname\fP, the \fImq_open\fP() function
|
||
|
shall fail and return an error without creating the message
|
||
|
queue.
|
||
|
.TP 7
|
||
|
O_EXCL
|
||
|
If O_EXCL and O_CREAT are set, \fImq_open\fP() shall fail if the message
|
||
|
queue \fIname\fP exists. The check for the existence
|
||
|
of the message queue and the creation of the message queue if it does
|
||
|
not exist shall be atomic with respect to other threads
|
||
|
executing \fImq_open\fP() naming the same \fIname\fP with O_EXCL and
|
||
|
O_CREAT set. If O_EXCL is set and O_CREAT is not set, the
|
||
|
result is undefined.
|
||
|
.TP 7
|
||
|
O_NONBLOCK
|
||
|
Determines whether an \fImq_send\fP() or \fImq_receive\fP() waits
|
||
|
for resources or messages that are not currently available, or fails
|
||
|
with \fIerrno\fP set to [EAGAIN]; see \fImq_send\fP() and \fImq_receive\fP()
|
||
|
for details.
|
||
|
.sp
|
||
|
.LP
|
||
|
The \fImq_open\fP() function does not add or remove messages from
|
||
|
the queue.
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
Upon successful completion, the function shall return a message queue
|
||
|
descriptor; otherwise, the function shall return
|
||
|
(\fBmqd_t\fP)-1 and set \fIerrno\fP to indicate the error.
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
The \fImq_open\fP() function shall fail if:
|
||
|
.TP 7
|
||
|
.B EACCES
|
||
|
The message queue exists and the permissions specified by \fIoflag\fP
|
||
|
are denied, or the message queue does not exist and
|
||
|
permission to create the message queue is denied.
|
||
|
.TP 7
|
||
|
.B EEXIST
|
||
|
O_CREAT and O_EXCL are set and the named message queue already exists.
|
||
|
.TP 7
|
||
|
.B EINTR
|
||
|
The \fImq_open\fP() function was interrupted by a signal.
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The \fImq_open\fP() function is not supported for the given name.
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
O_CREAT was specified in \fIoflag\fP, the value of \fIattr\fP is not
|
||
|
NULL, and either \fImq_maxmsg\fP or \fImq_msgsize\fP
|
||
|
was less than or equal to zero.
|
||
|
.TP 7
|
||
|
.B EMFILE
|
||
|
Too many message queue descriptors or file descriptors are currently
|
||
|
in use by this process.
|
||
|
.TP 7
|
||
|
.B ENAMETOOLONG
|
||
|
The length of the \fIname\fP argument exceeds {PATH_MAX} or a pathname
|
||
|
component is longer than {NAME_MAX}.
|
||
|
.TP 7
|
||
|
.B ENFILE
|
||
|
Too many message queues are currently open in the system.
|
||
|
.TP 7
|
||
|
.B ENOENT
|
||
|
O_CREAT is not set and the named message queue does not exist.
|
||
|
.TP 7
|
||
|
.B ENOSPC
|
||
|
There is insufficient space for the creation of the new message queue.
|
||
|
.sp
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fImq_close\fP() , \fImq_getattr\fP() , \fImq_receive\fP() , \fImq_send\fP()
|
||
|
, \fImq_setattr\fP() , \fImq_timedreceive\fP() , \fImq_timedsend\fP()
|
||
|
, \fImq_unlink\fP() , \fImsgctl\fP() , \fImsgget\fP() , \fImsgrcv\fP()
|
||
|
, \fImsgsnd\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
||
|
\fI<mqueue.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|