[Previous] [Contents] [Index] [Next]

Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

mq_open()

Open a message queue

Synopsis:

#include <mqueue.h>

mqd_t mq_open( const char * name, 
               int oflag,
               ... )

Arguments:

name
The name of the message queue that you want to open; see below.
oflag
You must specify one of O_RDONLY (receive-only), O_WRONLY (send-only) or O_RDWR (send-receive). In addition, you can OR in the following constants to produce the following effects:

If you set O_CREAT in the oflag argument, you must also pass these arguments to mq_open():

mode
The file permissions for the new queue. For more information, see "Access permissions" in the documentation for stat().

If you set any bits other than file permission bits, they're ignored. Read and write permissions are analogous to receive and send permissions; execute permissions are ignored.

mq_attr
NULL, or a pointer to an mq_attr structure that contains the attributes that you want to use for the new queue. For more information, see mq_getattr().

If mq_attr is NULL, the following default attributes are used -- depending on which implementation of message queues you're using -- provided that you didn't override the defaults when you started the message-queue server:

Attribute Traditional Alternate
mq_maxmsg 1024 64
mq_msgsize 4096 256
mq_flags 0 0

If mq_attr isn't NULL, the new queue adopts the mq_maxmsg and mq_msgsize of mq_attr. The mq_flags flags field is ignored.

Library:

Description:

The mq_open() function opens a message queue referred to by name, and returns a message queue descriptor by which the queue can be referenced in the future.


Note: Neutrino supports two implementations of message queues: a traditional implementation, and an alternate one that uses asynchronous messages. For more information, see the entry for mq and mqueue in the Utilities Reference.

The name is interpreted as follows:

name Pathname space entry
entry cwd/entry
/entry /dev/mqueue/entry using the traditional (mqueue) implementation, or /dev/mq/entry using the alternate (mq) implementation
entry/newentry cwd/entry/newentry
/entry/newentry /entry/newentry

where cwd is the current working directory for the program at the point that it calls mq_open().


Note: If you want to open a queue on another node, you have to use the traditional (mqueue) implementation and specify the name as /net/node/mqueue_location.

If name doesn't exist, mq_open() examines the third and fourth parameters: a mode_t and a pointer to an mq_attr structure.

The only time that a call to mq_open() with O_CREAT set fails is if you open a message queue and later unlink it, but never close it. Like their file counterparts, an unlinked queue that hasn't yet been closed must continue to exist; an attempt to recreate such a message queue fails, and errno is set to ENOENT.


Note: Message queues persist -- like files -- even after the processes that created them end. A message queue is destroyed when the last process connected to it unlinks from the queue by calling mq_unlink().

Returns:

A valid message queue descriptor if the queue is successfully created, or -1 (errno is set).

Errors:

EACCES
The message queue exists, and you don't have permission to open the queue under the given oflag, or the message queue doesn't exist, and you don't have permission to create one.
EEXIST
You specified the O_CREAT and O_EXCL flags in oflag, and the queue name exists.
EINTR
The operation was interrupted by a signal.
EINVAL
You specified the O_CREAT flag in oflag, and mq_attr wasn't NULL, but some values in the mq_attr structure were invalid.
ELOOP
Too many levels of symbolic links or prefixes.
EMFILE
Too many file descriptors are in use by the calling process.
ENAMETOOLONG
The length of name exceeds PATH_MAX.
ENFILE
Too many message queues are open in the system.
ENOENT
You didn't set the O_CREAT flag, and the queue name doesn't exist.
ENOSPC
The message queue server has run out of memory.
ENOSYS
The mq_open() function isn't implemented for the filesystem specified in name.

Classification:

POSIX 1003.1 MSG

Safety:
Cancellation point No
Interrupt handler No
Signal handler No
Thread Yes

See also:

mq_close(), mq_getattr(), mq_notify(), mq_receive(), mq_send(), mq_setattr(), mq_timedreceive(), mq_timedsend(), mq_unlink()

mq, mqueue in the Utilities Reference


[Previous] [Contents] [Index] [Next]