RTEMS 4.6.1 On-Line Library

Message Passing Manager mq_open - Open a Message Queue

RTEMS POSIX API User's Guide

16.4.1: mq_open - Open a Message Queue

CALLING SEQUENCE:

#include <mqueue.h>

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

STATUS CODES:

EACCES - Either the message queue exists and the permissions requested in oflags were denied, or the message does not exist and permission to create one is denied.

EEXIST - You tried to create a message queue that already exists.

EINVAL - An inappropriate name was given for the message queue, or the values of mq-maxmsg or mq_msgsize were less than 0.

ENOENT - The message queue does not exist, and you did not specify to create it.

EINTR - The call to mq_open was interrupted by a signal.

EMFILE - The process has too many files or message queues open. This is a process limit error.

ENFILE - The system has run out of resources to support more open message queues. This is a system error.

ENAMETOOLONG - mq_name is too long.

DESCRIPTION:

The mq_open () function establishes the connection between a process and a message queue with a message queue descriptor. If the message queue already exists, mq_open opens it, if the message queue does not exist, mq_open creates it. Message queues can have multiple senders and receivers. If mq_open is successful, the function returns a message queue descriptor. Otherwise, the function returns a -1 and sets 'errno' to indicate the error.

The name of the message queue is used as an argument. For the best of portability, the name of the message queue should begin with a "/" and no other "/" should be in the name. Different systems interpret the name in different ways.

The oflags contain information on how the message is opened if the queue already exists. This may be O_RDONLY for read only, O_WRONLY for write only, of O_RDWR, for read and write.

In addition, the oflags contain information needed in the creation of a message queue. O_NONBLOCK - If the non-block flag is set then the message queue is non-blocking, and requests to send and receive messages do not block waiting for resources. If the flag is not set then the message queue is blocking, and a request to send might have to wait for an empty message queue. Similarly, a request to receive might have to wait for a message to arrive on the queue. O_CREAT - This call specifies that the call the mq_open is to create a new message queue. In this case the mode and attribute arguments of the function call are utilized. The message queue is created with a mode similar to the creation of a file, read and write permission creator, group, and others.

The geometry of the message queue is contained in the attribute structure. This includes mq_msgsize that dictates the maximum size of a single message, and the mq_maxmsg that dictates the maximum number of messages the queue can hold at one time. If a NULL is used in the mq_attr argument, then the message queue is created with implementation defined defaults. O_EXCL - is always set if O_CREAT flag is set. If the message queue already exists, O_EXCL causes an error message to be returned, otherwise, the new message queue fails and appends to the existing one.

NOTES:

The mq_open () function does not add or remove messages from the queue. When a new message queue is being created, the mq_flag field of the attribute structure is not used.

RTEMS POSIX API User's Guide