mq_open(2)

NAME

mq_open — create or open a message queue

SYNOPSIS

#include <sys/mqueue.h> 

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

Remarks

The ANSI C ", ... " construct specifies a variable length argument list whose optional members are given in the associated comment (/* */).

DESCRIPTION

The mq_open() system call establishes a connection between a process and a message queue. It returns a new message queue descriptor which is used by other message queue system calls to refer to that queue.

The name argument points to the message queue name, and must conform to the rules listed in Message Queue Naming Convention.

The oflag argument is the bitwise inclusive OR of the flags listed in Read-Write Flags, and General Flags below.

The new message queue descriptor returned, remains open across the fork() system call and is inherited by the child process.

Read-Write Flags

The value of oflag must be composed by taking the inclusive OR of exactly one of the following flags:

O_RDONLY: Open for receiving only.
O_WRONLY: Open for sending only.
O_RDWR: Open for sending and receiving.

General Flags

Any combination of the following flags may also be used in setting the value of oflag.

O_CREAT: This flag must be used to create a message queue, and it uses two additional arguments: mode which is of type mode_t, and attr which is a pointer to a mq_attr structure. If a message queue with name, name, exists, this flag has no effect, except as noted under O_EXCL. Otherwise a new message queue is created. The user ID of the queue will be set to the effective user ID of the process, and the group ID of the queue will be set to the effective group ID of the process. The "file permission bits" will be set to the value of mode. If attr is NULL, the message queue is created with default attributes - MQ_MAXMSG and MQ_MSGSIZE (defined in sys/mqueue.h) If attr is non-NULL and 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 O_EXCL and O_CREAT are set in oflag and the named message queue exists, mq_open() will fail. The O_CREAT flag is ignored if O_CREAT is not set in oflag.
O_NONBLOCK: This flag is used to specify the blocking status of the message queue descriptor and determines whether a mq_send() or a mq_receive() will wait for resources or messages respectively, that are not currently available, or fail with errno set to EAGAIN.

Message Queue Naming Convention

A valid message queue name string, must conform to path name construction rules. In addition it must also meet the following specifications:

a.: Begin with a slash character.
b.: Contain no path name component consisting of a dot or dot-dot. For example, /./tmp and /../tmp are invalid.
c.: Contain no illegal characters.
d.: Contain no path name components longer that _POSIX_NAME_MAX.
e.: Entire name should not be longer that _POSIX_PATH_MAX.

To use this function, link in the realtime library by specifying -lrt on the compiler or linker command line.

Security Restrictions

Some or all of the actions associated with this system call are subject to compartmental restrictions. See compartments(5) for more information about compartmentalization on systems that support that feature.

Compartmental restrictions can be overridden if the process possesses the COMMALLOWED privilege (PRIV_COMMALLOWED). Processes owned by the superuser may not have this privilege. Processes owned by any user may have this privilege, depending on system configuration.

Some or all of the actions associated with this system call require the DACWRITE privilege (PRIV_DACWRITE). Processes owned by the superuser have this privilege. Processes owned by other users may have this privilege, depending on system configuration.

See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

RETURN VALUE

mq_open() returns the following values:

n: Successful completion. n is a message queue descriptor for the opened message queue and is greater than or equal to 0.
-1: Failure. errno is set to indicate the error.

ERRORS

If mq_open() fails, errno is set to one of the following values:

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 queue is denied.

EEXIST

The O_CREAT and O_EXCL flags are set in oflag and the named message queue exists.

EINTR

mq_open() was interrupted by a signal.

EINVAL

The argument name, does not conform to the Message Queue Naming Convention.

O_CREAT has been specified in oflag, the value of attr is not NULL, and either mq_maxmsg or mq_msgsize is less than or equal to zero.

EMFILE

Too many message queue descriptors are currently in use by this process.

ENAMETOOLONG

The length of the name string exceeds PATH_MAX bytes, or the length of a (path name) component of the name string exceeds NAME_MAX bytes while _POSIX_NO_TRUNC is in effect.

ENFILE

Too many message queues are currently open in the system.

ENOENT

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

ENOSPC

There are insufficient resources for the creation of the new message queue.

ENOSYS

mq_open() is not supported by the implementation.

STANDARDS CONFORMANCE

mq_open(): POSIX 1003.1b