mq_open(3P4) — CX/UX Programmer’s Reference Manual

NAME

mq_open − open a message queue

SYNOPSIS

#include <mqueue.h>
mqd_t mq_open (name, oflag [ , mode, attr ] )
char ∗name;
int oflag;
mode_t mode;
struct mq_attr ∗attr;

DESCRIPTION

The mq_open() routine creates a message queue descriptor that establishes an association between a process and a message queue. The message queue descriptor is used to refer to that message queue when invoking other functions. When the message queue is created, it has an associated set of attributes (see mq_getattr(3P4)) and access permissions.

The name argument points to a null-terminated string naming a message queue. The name does not appear in the file system and is not visible to other functions that take path names as arguments. name must consist of less than {NAME_MAX} (defined in the file /usr/include/limits.h) characters from the portable file name character set. Slash (/) characters are not allowed in name. The current working directory does not affect the interpretation of name. Processes calling mq_open() with the same value of name refer to the same message queue. If the name argument is not the name of an existing message queue and creation of a message queue is not requested, mq_open() will fail and return an error.

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

The value of oflag is the bitwise inclusive OR of values from the following list. Applications shall specify exactly one of the first three values (access permissions) and one or more of the other values listed below:

O_RDONLY Open the message queue for receiving messages. The process can use the returned message queue descriptor with mq_receive() but not mq_send().

O_WRONLY Open the queue for sending messages. The process can use the returned message queue descriptor with mq_send() but not mq_receive().

O_RDWR Open the queue for both receiving and sending messages.

O_CREAT When this flag is specified, two extra arguments, mode and attr, are required. If the message queue exists, this flag has no effect. Otherwise, the owner ID of the message queue is set to the effective user ID of the calling process; the group ID of the message queue is set to the effective group ID of the calling process; and the low-order 9 bits of the file mode are set to the value of mode. Note that the value of mode is modified by any bits set in the file creation mode mask of the process. See umask(2). If name has already been used to create a message queue that is still open, then this flag has no effect except as noted under O_EXCL below. Otherwise, an empty message queue is created. If attr is NULL, the message queue is created with the default message queue attributes. By default, a message queue holds a maximum of 80 messages, and each message can be composed of a maximum of 40 characters. If attr is non-NULL, the message queue attributes are set according to the attribute argument attr.

O_EXCL If O_EXCL and O_CREAT are set, mq_open will fail if the message queue name already exists.

O_NONBLOCK The setting of this flag is associated with the open message queue descriptor and determines whether an mq_send() or mq_receive() will block when message slots or messages are not currently available.

RETURN VALUE

Upon successful completion, a message queue descriptor is returned. If any of the following conditions occur, the mq_open() function shall return ((mqd_t) -1) and set errno
to the corresponding value:

[EACCES] The permissions specified by oflag are denied to this process because of the mode used during creation of the message queue.

[EEXIST] O_CREAT and O_EXCL are set, and a message queue associated with name already exists.

[EMFILE] This process cannot attach any more shared memory segments and, thus, cannot attach the message queue, or this process cannot open a new file descriptor because too many file descriptors are currently in use by this process.

[ENAMETOOLONG] The length of the name argument exceeds the limit {NAME_MAX}.

[ENFILE] An attempt was made to create a message queue, but the system-wide limit on the number of shared memory identifiers would be exceeded by creating this message queue.

[ENOENT] O_CREAT is not set and no message queue exists that was created using name.

[ENOMEM] The value of one of the message queue attributes would cause some system resource limit to be exceeded.

[EINVAL] The message queue exists, but it has different attributes from those specified.

FILES

/usr/lib/libposix4.a

WARNING

The interface to mq_open() is based on IEEE Draft Standard P1003.4/D12. This is an unapproved draft, subject to change. Use of information contained in this unapproved draft is at your own risk. This interface will change to reflect any changes made by future drafts of POSIX 1003.4.

Museum

Related Articles