NAME

       mq_open - open a message queue (REALTIME)

SYNOPSIS

       #include <mqueue.h>

       mqd_t mq_open(const char *name, int oflag, ...);

DESCRIPTION

       The  mq_open()  function  shall  establish  the connection between a process and a message
       queue with a message queue descriptor. It shall create 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  functions  to
       refer  to that message queue. The name argument points to a string naming a message queue.
       It is unspecified whether the name appears in the file system  and  is  visible  to  other
       functions  that  take  pathnames  as  arguments.   The  name argument shall conform to the
       construction rules for a pathname. If name begins with the slash character, then processes
       calling  mq_open()  with  the  same  value  of  name shall refer to the same message queue
       object, as long as that name has not been removed. If name does not begin with  the  slash
       character,  the  effect is implementation-defined.  The interpretation of slash characters
       other than the leading slash character in name is  implementation-defined.   If  the  name
       argument  is  not  the  name  of  an existing message queue and creation is not requested,
       mq_open() shall fail and return an error.

       A message queue descriptor may be implemented using  a  file  descriptor,  in  which  case
       applications can open up to at least {OPEN_MAX} file and message queues.

       The  oflag  argument requests the desired receive and/or send access to the message queue.
       The requested access permission to receive messages or send messages shall be  granted  if
       the  calling  process  would  be  granted  read  or  write  access,  respectively,  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 modes) below in
       the value of oflag:

       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(). 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  mq_send()  but  not  mq_receive().   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  O_RDONLY  and  O_WRONLY.  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 oflag:

       O_CREAT
              Create a message queue. It requires two additional arguments: mode, which shall  be
              of type mode_t, and attr, which shall be a pointer to an mq_attr structure.  If the
              pathname name has already been used to create a message queue  that  still  exists,
              then  this  flag  shall  have no effect, except as noted under O_EXCL. Otherwise, a
              message queue shall be created without any messages in  it.  The  user  ID  of  the
              message  queue  shall be set to the effective user ID of the process, and the group
              ID of the message queue shall be set to the effective group ID of the process.  The
              file  permission  bits  shall  be set to the value of mode. When bits in mode other
              than file permission bits are set, the effect is implementation-defined. If attr is
              NULL,  the  message  queue  shall  be  created  with implementation-defined default
              message queue attributes. If attr is non-NULL  and  the  calling  process  has  the
              appropriate   privilege  on  name,  the  message  queue  mq_maxmsg  and  mq_msgsize
              attributes shall be set to the values of the corresponding members in  the  mq_attr
              structure  referred  to  by attr. If attr is non-NULL, but the calling process does
              not have the appropriate privilege on name, the mq_open() function shall  fail  and
              return an error without creating the message queue.

       O_EXCL If  O_EXCL  and  O_CREAT  are  set,  mq_open() shall fail 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 shall be atomic with respect to other threads
              executing mq_open() naming the same name with O_EXCL and O_CREAT set. If O_EXCL  is
              set and O_CREAT is not set, the result is undefined.

       O_NONBLOCK
              Determines  whether  an  mq_send()  or mq_receive() waits for resources or messages
              that are not currently  available,  or  fails  with  errno  set  to  [EAGAIN];  see
              mq_send() and mq_receive() for details.

       The mq_open() function does not add or remove messages from the queue.

RETURN VALUE

       Upon  successful  completion,  the  function  shall  return  a  message  queue descriptor;
       otherwise, the function shall return (mqd_t)-1 and set errno to indicate the error.

ERRORS

       The mq_open() function shall fail if:

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

       EEXIST O_CREAT and O_EXCL are set and the named message queue already exists.

       EINTR  The mq_open() function was interrupted by a signal.

       EINVAL The mq_open() function is not supported for the given name.

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

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

       ENAMETOOLONG
              The  length  of  the  name  argument  exceeds {PATH_MAX} or a pathname component is
              longer than {NAME_MAX}.

       ENFILE Too many message queues are currently open in the system.

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

       ENOSPC There is insufficient space for the creation of the new message queue.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       mq_close() , mq_getattr() , mq_receive() , mq_send() , mq_setattr() , mq_timedreceive()  ,
       mq_timedsend()  ,  mq_unlink()  ,  msgctl()  ,  msgget()  , msgrcv() , msgsnd() , the Base
       Definitions volume of IEEE Std 1003.1-2001, <mqueue.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2003  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .