open a message queue
#include <mqueue.h>
mqd_t mq_open( const char *name, int oflag, ... )
mq_open() opens a message queue referred to by name, and
returns a message-queue descriptor by which the queue can be referenced in the
future. If the message queue with the given name doesn't exist,
mq_open() examines the third and fourth arguments:
- mode_t mode
- mq_attr *attr
The arguments are used as described below.
- name
- All message queues exist in the Mqueue namespace
(/dev/mqueue). Any leading slash present in
name is removed, and any other slashes are
converted to periods (.).
Neither the message queue namespace nor the node of the message queue
server should be prepended to name. Thus, a name
of either /dev/mqueue/my_mqueue or
//71/my_mqueue produces undesirable results.
To address the request to a message queue server on a different node,
the desired node number should be set in the environment variable
MQ_NODE.
- oflag
- One of the following must be specified in oflags:
- O_RDONLY
- receive-only
- O_WRONLY
- send-only
- O_RDWR
- send-receive
In addition, you can add the following constants with an OR operation, to
produce the following effects:
- O_CREAT
- If the queue with the given name doesn't exist, this
flag instructs the server to create a new message queue and assign
name to it.
If this flag is specified, then the third and fourth parameters of
mq_open() are examined (see mode and
attr, below). The only time that an
mq_open() call with O_CREAT may fail is
if a message queue is opened, and later unlinked, but never closed.
Like their file counterparts, an unlinked queue that hasn't yet
been closed must continue to exist. For this reason, an attempt
to re-create such a message queue fails, and errno
is set to ENOENT.
- O_EXCL
- If both O_EXCL and O_CREAT are set,
and a message queue name exists, the call fails, and
sets errno to EBUSY. Otherwise, the
queue is created normally. If O_EXCL is set without
O_CREAT, it's ignored.
- O_NONBLOCK
- Under normal message queue operation, an mq_send() or
mq_receive() could block (if the message queue is full
or empty, respectively). If this flag is set, these calls
never block. If the queue isn't in a condition to perform the
given call, then errno is set to
EAGAIN, and the call returns an error.
- mode
- If the queue name is to be created, then the new queue
has the file permission bits as specified in mode. If any
bits are set other than file permission bits, they are ignored.
Read and write permissions are analogous to receive and send permissions,
respectively; execute permissions are ignored.
- attr
- Like mode, this argument is only examined if the queue
name is to be created. It's a pointer to an
mq_attr structure that's to contain the attributes for
the new
queue. If this is NULL, the following
default attributes are used (provided that no defaults were specified
when starting the message queue server):
Variable
|
Default value
|
mq_maxmsg
|
1024
|
mq_msgsize
|
4096
|
mq_flags
|
0
|
According to the POSIX 1003.4 documentation, if the attr
pointer is non-NULL, then the new queue adopts the
mq_maxmsg and mq_msgsize of attr.
However, no mention is made of consultation of the mq_flags
field. In the QNX implementation, the mq_flags field is
consulted. This is due to the fact that some of the extended QNX
options cannot be changed at runtime, and must be specified on
creation. See the entry for
mq_setattr() for the
meaning of these flags.
Calling open() with a name that resolves to one in the message
queue server's path-name space (for example,
/dev/mqueue/my_queue) is equivalent to calling
mq_open() with name set to the last component of the
pathname (for example, mq_queue). If the queue doesn't exist,
and O_CREAT was specified in the oflag to
open(), then the default mq_attr structure is used.
If the queue was successfully created, a valid message queue descriptor
is returned. If not, -1 is returned, and errno is set.
If the mq_open() function fails, errno may be set to
one of the following values:
- EACCES
- This value indicates one of the following:
- the message queue exists, but you don't have permission to open
it under the given oflag.
- the message queue doesn't exist, and you don't have
permission to create one.
- EEXIST
- O_CREAT and O_EXCL have been specified
in oflag, and the queue name exists.
- EINTR
- The operation was interrupted by a signal.
- EINVAL
- This value indicates one of the following:
- O_CREAT was specified in oflag, and
attr wasn't NULL, but some value or values
in the mq_attr structure were invalid.
- The name parameter is NULL.
- EMFILE
- Too many file descriptors are in use by the calling process.
- ENAMETOOLONG
- The length of name exceeds PATH_MAX.
- ENOENT
- O_CREAT hasn't been set, and the queue name
doesn't exist.
- ENOSPC
- The message queue server has run out of memory.
POSIX 1003.4 with extensions
Safety: | |
Interrupt handler |
No |
Signal handler |
Yes, but modifies errno |
Thread |
No |
In order to use the mq_... functions, you must:
- Link your application with the mqueue library
(specify -lmqueue in your cc command).
- Start the message queue server, Mqueue.
For more information, see the QNX Utilities Reference.
errno,
mq_close(),
mq_getattr(),
mq_notify(),
mq_receive(),
mq_send(),
mq_setattr(),
mq_unlink(),
open()
chapter on POSIX.4 message queues