Index for Section 3

Alphabetical listing for M

Bottom of page

mq_open(3)
NAME
  mq_open - Establishes the connection between a message queue and a message
  queue descriptor (P1003.1b)

LIBRARY
  Realtime Library (librt.so, librt.a)

SYNOPSIS
  #include <mqueue.h>

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

PARAMETERS
  *name	  Specifies a pointer to the name of a string naming the message
	  queue.  The string can be a pathname.

  oflag	  Specifies the request for receive or send access to the message
	  queue, as well as the blocking attributes of the resulting open
	  descriptor for the calling process.

  This value of this argument is the bitwise inclusive OR of the values from
  the following list of flags.	An application must specify exactly one of
  the first three flags:

  O_RDONLY	 Opens the message queue for receiving messages.  This
		 enables calls to the mq_receive function but not calls to
		 the mq_send function for the calling process.	Note that
		 each process has its own read/write access to a queue.

  O_WRONLY	 Opens the queue for sending messages.	This enables calls to
		 the mq_send function but not calls to the mq_receive
		 function for the calling process.

  O_RDWR	 Opens the queue for receiving and sending messages for the
		 calling process.

  Any combination of the following flags is valid:

  O_CREAT	 Creates a message queue.  Use of this flag requires
		 specification of two additional arguments:  mode, which is
		 of type mode_t, and attr, which points to a mq_attr
		 structure.  If name has already been used to create a
		 message queue that is still open, this flag has no effect,
		 except as noted under O_EXCL.	Otherwise, a message queue is
		 created.  The ID of the message queue becomes the effective
		 user ID, and the group ID of the message queue becomes the
		 effective group ID of the process.  The mode argument sets
		 the file permission bits.  If the attr argument is NULL, the
		 function creates the message queue with default attributes.
		 If the attr argument is not NULL, and the calling process
		 has appropriate privilege or permission, the message queue
		 attributes are set as if the mq_setattr function were called
		 with the attribute argument attr.  If the attr argument is
		 not NULL, but the calling process does not have the
		 appropriate privilege or permission, the mq_open argument
		 fails and returns an error.

  O_EXCL	 Prevents the opening of a message queue if O_CREAT is set
		 and the message queue already exists.	Use this flag only in
		 combination with O_CREAT.

  O_NONBLOCK	 Allows calls to the mq_send and mq_receive functions to
		 continue execution while waiting for resources or messages.
		 When this flag is set and resources are not available, the
		 mq_send and mq_receive functions fail and errno is set to
		 EAGAIN.  This flag is a per-open descriptor flag, and
		 applies to the calling process only.  Each process has its
		 own blocking attributes for a queue.

DESCRIPTION
  The mq_open function establishes the connection between a message queue and
  a message queue descriptor.  This function creates a new open message queue
  description that refers to a specified message queue and a message queue
  descriptor that refers to that open message queue description.  The message
  queue descriptor is then available for use by other functions for reference
  to the message queue from the calling process.

RETURN VALUES
  On successful completion, this function returns a message queue descriptor.

  Otherwise, the function returns -1 and sets errno to indicate the error.

ERRORS
  The mq_open function fails under the following conditions:

  [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.

  [EFAULT]	 An internal virtual memory error occurred.

  [EINTR]	 The mq_open operation was interrupted by a signal.

  [EINVAL]	 The mq_open operation is not supported for the given name.
		 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 string exceeds {PATH_MAX}, or a
		 pathname component is longer than {NAME_MAX} while
		 {_POSIX_NO_TRUNC} is in effect.

  [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.

RELATED INFORMATION
  Functions: mq_close(3), mq_getattr(3), mq_receive(3), mq_send(3),
  mq_setattr(3), mq_unlink(3), mkfifo(3)

  Guide to Realtime Programming

Index for Section 3

Alphabetical listing for M

Top of page