mq_open Subroutine

Purpose

Opens a message queue.

Library

Standard C Library (libc.a)

Syntax

#include <mqueue.h>

mqd_t mq_open (name, oflag [mode, attr])
const char *name;
int oflag;
mode_t mode;
mq_attr *attr;

Description

The mq_open subroutine establishes a 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. The message queue descriptor is used by other subroutines to refer to that message queue.

The name parameter points to a string naming a message queue, and has no representation in the file system. The name parameter conforms to the construction rules for a pathname. It may or may not begin with a slash character, but contains at least one character. Processes calling the mq_open subroutine with the same value of name refer to the same message queue object, as long as that name has not been removed. If the name parameter is not the name of an existing message queue and creation is not requested, the mq_open subroutine will fail and return an error.

The oflag parameter requests the desired receive and send access to the message queue. The requested access permission to receive messages 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 the oflag parameter is the bitwise-inclusive OR of values from the following list. Applications specify exactly one of the first three values (access modes) below in the value of the oflag parameter:

O_RDONLY: Open the message queue for receiving messages. The process can use the returned message queue descriptor with the mq_receive subroutine, but not the mq_send subroutine. A message queue may be open multiple times in the same or different processes for receiving messages.
O_WRONLY: Open the queue for sending messages. The process can use the returned message queue descriptor with the mq_send subroutine but not the mq_receive subroutine. A message queue may be open multiple times in the same or different processes for sending messages.
O_RDWR: Open the queue for both receiving and sending messages. The process can use any of the functions allowed for the O_RDONLY and O_WRONLY flags. A message queue may be open multiple times in the same or different processes for sending messages.

Any combination of the remaining flags may be specified in the value of the oflag parameter:

O_CREAT: Create a message queue. It requires two additional arguments: mode, which is of mode_t type, and attr, which is a pointer to an mq_attr structure. If the pathname name has already been used to create a message queue that still exists, this flag has no effect, except as noted under the O_EXCL flag. Otherwise, a message queue is created without any messages in it. The user ID of the message queue is set to the effective user ID of the process, and the group ID of the message queue is set to the effective group ID of the process. The file permission bits are set to the value of mode. When bits in the mode parameter other than file permission bits are set, they have no effect. If attr is NULL, the message queue is created with default message queue attributes. Default values are 128 for mq_maxmsg and 1024 for mq_msgsize. If attr is non-NULL, the message queue mq_maxmsg and mq_msgsize attributes are set to the values of the corresponding members in the mq_attr structure referred to by attr.
O_EXCL: If the O_EXCL and O_CREAT flags are set, the mq_open subroutine fails if the message queue name 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 the O_EXCL and O_CREAT flags set. If the O_EXCL flag is set and the O_CREAT flag is not set, the O_EXCL flag is ignored.
O_NONBLOCK: Determines whether the mq_send or mq_receive subroutine waits for resources or messages that are not currently available, or fails with errno set to EAGAIN; see mq_send Subroutine and mq_receive Subroutine for details.

The mq_open subroutine does not add or remove messages from the queue.

Parameters

Item	Description
name	Points to a string naming a message queue.
oflag	Requests the desired receive and send access to the message queue.
mode	Specifies the value of the file permission bits. Used with O_CREAT to create a message queue.
attr	Points to an mq_attr structure. Used with O_CREAT to create a message queue.

Return Values

Upon successful completion, the mq_open subroutine returns a message queue descriptor. Otherwise, it returns (mqd_t)-1 and sets errno to indicate the error.

Error Codes

The mq_open subroutine fails if:

Item	Description
EACCES	The message queue exists and the permissions specified by the oflag parameter are denied.
EEXIST	The O_CREAT and O_EXCL flags are set and the named message queue already exists.
EFAULT	Invalid used address.
EINVAL	The mq_open subroutine is not supported for the given name.
EINVAL	The O_CREAT flag was specified in the oflag parameter, the value of attr is not NULL, and either mq_maxmsg or mq_msgsize was less than or equal to zero.
EINVAL	The oflag parameter value is not valid.
EMFILE	Too many message queue descriptors are currently in use by this process.
ENAMETOOLONG	The length of the name parameter exceeds PATH_MAX or a pathname component is longer than NAME_MAX.
ENFILE	Too many message queues are currently open in the system.
ENOENT	The O_CREAT flag is not set and the named message queue does not exist.
ENOMEM	Insufficient memory for the required operation.
ENOSPC	There is insufficient space for the creation of the new message queue.
ENOTSUP	This function is not supported with processes that have been checkpoint-restart'ed.