mq_open(3c)

NAME
     mq_open - open/create a message queue

C SYNOPSIS
     #include <mqueue.h>

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

DESCRIPTION
     mq_open is used to open or to create and open a message queue. It returns
     a message queue descriptor that is used as the handle for other
     operations on the queue. mq_name points to a path name that is
     constructed using the standard filename conventions.

     The oflag argument is used to specify send, receive or send/receive
     access to the queue.  It is also used to specify creation of the queue.
     The following oflags may be selected (the first three flags are mutually
     exclusive):

     O_RDONLY     Open the queue for receiving messages, but not for sending
                  messages.

     O_WRONLY     Open the queue for sending messages, but not for receiving
                  messages.

     O_RDWR       Open the queue for both sending and receiving messages.

     O_NONBLOCK   Do not block on mq_send when sending messages to a full
                  queue (or if required resources are unavailable) or on
                  mq_receive when receiving messages from a empty queue (or if
                  required resources are unavailable).  [see mq_send(3c) and
                  mq_receive(3c)].

     O_CREAT      Create the message queue.  If the message queue exists, this
                  flag has no effect, except as noted under O_EXCL below.
                  Otherwise, the third argument, mode and the fourth argument
                  mq_attr are used to create the message queue. The uid and
                  gid of the queue are set to the effective uid and gid,
                  respectively, of the process. The mode for the queue is set
                  to the value of the mode argument, similar to that for file
                  creation. The mode of queue specifies the read and write
                  (corresponding to receive and send) permission for user,
                  group and the world. The queue is created according to the
                  specifications in the fourth argument, mq_attr. If this
                  argument is non-NULL, the mq_msgsize field of the mq_attr
                  structure specifies the maximum size of a single message in
                  the queue. Messages larger than this size sent to the queue
                  will generate an error. The mq_maxmsg field specifies the
                  maximum number of messages on the queue at any one time.  If
                  the mq_attr argument is NULL, the queue is created using the
                  default values of 32 and 64 for mq_maxmsg and mq_msgsize,
                  respectively.

     O_EXCL       If O_EXCL and O_CREAT are set, mq_open will fail if the
                  queue exists. The check for the existence of the file and
                  the creation of the queue if it does not exist is atomic
                  with respect to other processes executing mq_open with the
                  same name in the same directory with O_EXCL and O_CREAT set.

     When a new message queue is created, the queue is void of messages.
     Opening an existing message queue has no effect on its contents.

     Message queue state is preserved across application termination, but the
     contents of a queue after system reboot are undefined.

     POSIX message queues are compatible across all MIPS ABIs: o32, n32 and
     64.

     mq_open will fail if one or more of the following conditions are true:

     [EACCES]       The message queue does not exist and permission to create
                    the queue is denied.

     [EACCES]       The message queue exists, but the permissions in oflag are
                    denied.

     [EACCES]       A component of mq_name has no search permission or does
                    not exist.

     [EEXIST]       O_CREAT and O_EXCL are set, and the message queue exists.

     [EFAULT]       mq_name points outside the allocated address space of the
                    process.

     [EINTR]        A signal interrupted the mq_open function call.

     [EINVAL]       The values of mq_msgsize and mq_maxmsg fields in the
                    mq_attr structure are outside the valid range. Invalid
                    flags specified in the oflag argument.

     [EMFILE]       The process has too many open files or message queues[see
                    getrlimit(2)].

     [ENAMETOOLONG] The length of the mq_name argument exceeds {PATH_MAX}, or
                    the length of a mq_name component exceeds {NAME_MAX} while
                    {_POSIX_NO_TRUNC} is in effect.

     [ENFILE]       There are too many files and/or message queues in the
                    system.

     [ENOENT]       O_CREAT is not set and the named queue does not exist.

     [ENOENT]       O_CREAT is set and a component of the mq_name does not
                    exist or is not directory.

     [ENOMEM]       The system is unable to allocate a message queue
                    descriptor.

     [ENOSPC]       O_CREAT is set, the message queue does not exist and the
                    system cannot create the queue due to lack of resources.

SEE ALSO
     mq_close(3c), open(3c), getdtablesize(2), getrlimit(2), intro(3c),
     mq_receive(3c), mq_send(3c), mq_getattr(3c), mq_setattr(3c),
     mq_notify(3c), umask(2)

DIAGNOSTICS
     Upon successful completion, the message queue descriptor is returned.
     Otherwise, a value of -1 is returned and errno is set to indicate the
     error.