mq_open()

open a message queue 

Realtime Function


SYNOPSIS

#include <mqueue.h>

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


DESCRIPTION

The mq_open() function establishes the connection between a process and a message queue with a message queue descriptor. It creates an open message queue description that refers to the message queue, and a message queue descriptor that refers to that open message queue description. Other functions use the message queue descriptor to refer to that message queue.

The name argument points to a string naming a message queue. The name string must begin with a slash character (/) and must conform to the rules for constructing a a path name. Processes calling mq_open() with the same value of name refer to the same message queue object, as long as that name has not been removed.

If name not the name of an existing message queue and creation is not requested, mq_open() fail and returns error.

POSIX_MQ_OPEN_MAX, defined in the limits.h header, specifies the maximum number of message queues that can exist system wide.

The oflag argument requests the desired receive and/or send access to the message queue. The requested access permission to receive or send messages is granted if the calling process would be granted read or write access, respectively, to an equivalently protected file.

The value of oflag is the bitwise-inclusive OR of values from the following list. One (and only one) of the first three access modes listed must be included in the value of oflag:

O_RDONLY 

Opens the message queue for receiving messages. The process can use the returned message queue descriptor with the mq_receive() function, but not with the mq_send() function. A message queue may be open multiple times in the same or different processes for receiving messages.

O_WRONLY 

Opens the queue for sending messages. The process can use the returned message queue descriptor with the mq_send() function but not with the mq_receive() function. A message queue may be open multiple times in the same or different processes for sending messages.

O_RDWR 

Opens 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.

The oflag value may contain any combination of the following flags:

O_CREAT 

Creates a message queue. When this flag is specified, mq_open() also requires the mode and attr arguments. The mode argument is of type mode_t, while the attr attribute is a pointer to a mq_attr structure. If a message queue created with the name argument already exists, this flag is ignored (except as described under O_EXCL). If no such queue exists, mq_open() creates an empty message queue with a user ID and a group set to the effective user ID and the effective group ID, respectively, of the process. The file permission bits of this queue are set to the file permission bits of mode group ID of the process. If attr is NULL, mq_open() creates the message queue with the default message queue attributes: 10 messages, each of size _POSIX_PIPE_BUF. If attr is non-NULL and the calling process has the appropriate privilege on name, mq_open() sets mq_maxmsg and mq_msgsize attributes of the created queue to the values of the corresponding members in the mq_attr structure pointed to by attr. If attr is non-NULL and the calling process does not have the appropriate privilege on name, mq_open() fails without creating a message queue.

O_EXCL 

If both the O_EXCL and O_CREAT flags are set in oflag, mq_open() fails if the message queue name already exists. The check for the existence of the message queue and the creation of the message queue if it does not exist is atomic with respect to other threads executing mq_open() naming the same name with O_EXCL and O_CREAT set.

O_NONBLOCK 

Determines whether an mq_send() or mq_receive() function waits for resources or messages that are not currently available, or fails with errno set to EAGAIN. See the mq_receive() and mq_send() reference pages for more details.

mq_open() does not add or remove messages from the queue.


PARAMETERS

name 

Points to the name to be assigned to the newly created message queue.

oflag 

Is the bitwise-inclusive OR of the flags to be used when creating a new message queue.


RETURN VALUES

On success, mq_open() returns a message queue descriptor. On failure it returns (mqd_t)-1 and sets errno to one of the following:

EACCES 

The message queue exists and the permissions specified by oflag are denied, or the message queue does not exist and permission to create the message queue is denied.

EEXIST 

Both the O_CREAT and O_EXCL flags are set and the named message queue already exists.

EINTR 

mq_open() was interrupted by a signal.

EINVAL 

mq_open() is not supported for the given name.

EINVAL 

The O_CREAT flag is set in oflag, the value of attr is not NULL, and either mq_maxmsg or mq_msgsize was less than or equal to zero.

EMFILE 

The calling process is currently using too many message queue descriptors.

ENAMETOOLONG 

The name argument is longer than {PATH_MAX}.

ENFILE 

The system has too many message queues currently open.

ENOENT 

The O_CREAT flag is not set and the named message queue does not exist.

ENOSPC 

There is not enough space to create the new message queue.


CONFORMANCE

UNIX 03.


MULTITHREAD SAFETY LEVEL

MT-Safe.


PORTING ISSUES

None.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
mq_close(), mq_getattr(), mq_receive(), mq_send(), mq_setattr(), mq_timedreceive(), mq_timedsend(), mq_unlink(), msgctl(), msgget(), msgrcv(), msgsnd()


PTC MKS Toolkit 10.3 Documentation Build 39.