mq_open()

Open a message queue

Synopsis:

#include <mqueue.h>

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

Library:

libc

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.

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

name

The name of a message queue. For POSIX portability, name should start with a slash (/) and not contain any other slashes. In QNX, all message queues are placed under /dev/mqueue and /dev/mqueue is always prefixed to name.

oflag

Either O_RDONLY (receive-only), O_WRONLY (send-only) or O_RDWR (send-receive) must be specified in oflags. In addition, the following constants may be ORed in to produce the following effects:

O_CREAT

If name doesn't exist, this flag instructs the server to create a new message queue with the name name. If this flag is specified, then the third and fourth parameters of mq_open() are examined (see mode and mq_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 which hasn't yet been closed must continue to exist. For this reason, an attempt to recreate 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 errno is set to EEXIST. 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're ignored. Read and write permissions are analogous to receive and send permissions; execute permissions are ignored.

mq_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 which contains 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):

Member	Value
mq_maxmsg	1024
mq_msgsize	4096
mq_flags	0

If the pointer is non-NULL, then the new queue adopts the mq_maxmsg and mq_msgsize of mq_attr. The mq_flags flags field is ignored.

Returns:

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

Errors:

EACCES

The message queue exists, and the current user doesn't have permission to open the queue under the given oflag, or the message queue doesn't exist, and the current user doesn't have permission to create one.

EEXIST

The O_CREAT and O_EXCL flags have been specified in oflag, and the queue name exists.

EINTR

The operation was interrupted by a signal.

EINVAL

The O_CREAT flag was specified in oflag, mq_attr wasn't NULL, but some value or 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.

ENOENT

The O_CREAT flag hasn't been set, 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 (Realtime Extensions)

See also:

mq_close(), mq_receive(), mq_send(), mq_setattr(), mq_unlink()