Unix/Linux Go Back    


Linux 2.6 - man page for mq_open (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


MQ_OPEN(P)			    POSIX Programmer's Manual			       MQ_OPEN(P)

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 con-
       struction 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 equiva-
       lently protected file.

       The value of oflag is the bitwise-inclusive OR of values from the following list. Applica-
       tions  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 multi-
	      ple 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 multi-
	      ple 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  mes-
	      sage  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 mes-
	      sage queue attributes. If attr is non-NULL and the calling process has  the  appro-
	      priate  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; other-
       wise, 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 Defi-
       nitions 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				       MQ_OPEN(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:39 PM.