[Previous]
[Contents]
[Next]

mq_open()

open a message queue

Synopsis:

#include <mqueue.h>
mqd_t mq_open( const char *name, int oflag, ... )

Description:

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:

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.

Returns:

If the queue was successfully created, a valid message queue descriptor is returned. If not, -1 is returned, and errno is set.

Errors:

If the mq_open() function fails, errno may be set to one of the following values:

EACCES
This value indicates one of the following:
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:
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.

Classification:

POSIX 1003.4 with extensions

Safety:
Interrupt handler No
Signal handler Yes, but modifies errno
Thread No

Caveats:

In order to use the mq_... functions, you must:

See also:

errno, mq_close(), mq_getattr(), mq_notify(), mq_receive(), mq_send(), mq_setattr(), mq_unlink(), open()

chapter on POSIX.4 message queues


[Previous]
[Contents]
[Next]