Index for Section 2

Alphabetical listing for M

Bottom of page

msgctl(2)
NAME
  msgctl - Perform message control operations

SYNOPSIS
  #include <sys/msg.h>

  int msgctl(
	  int msqid,
	  int cmd,
	  struct msqid_ds *buf );

  Application developers might want to specify #include statements for
  <sys/types.h> and <sys/ipc.h> before the one for <sys/msg.h> if programs
  are being developed for multiple platforms.  The additional #include
  statements are not required on Tru64 UNIX systems or by ISO or X/Open
  standards, but may be required on other vendors' systems that conform to
  these standards.

STANDARDS
  Interfaces documented on this reference page conform to industry standards
  as follows:

  msgctl():  XSH4.0, XSH4.2, XSH5.0

  Refer to the standards(5) reference page for more information about
  industry standards and associated tags.

PARAMETERS
  msqid
      Specifies the message queue ID.

  cmd Specifies the type of command. The possible commands and the operations
      they perform are as follows:

      IPC_STAT
	  Queries the message queue ID by copying the contents of its
	  associated data structure into the buf structure.  The process must
	  have mandatory read access to the message queue with respect to all
	  access control policies.

      IPC_SET
	  Sets the message queue ID by copying values found in the buf
	  structure into corresponding fields in the msqid_ds structure
	  associated with the message queue ID. This operation is restricted.
	  The effective user ID of the calling process must be equal to that
	  of superuser or equal to the value of msg_perm.uid or msg_perm.cuid
	  in the associated msqid_ds structure.	 Only superuser can raise the
	  value of msg_qbytes.

      IPC_RMID
	  Removes the message queue ID and deallocates its associated
	  msqid_ds structure. This operation is restricted. The effective
	  user ID of the calling process must be equal to that of superuser
	  or equal to the value of msg_perm.uid or msg_perm.cuid in the
	  associated msqid_ds structure.

  buf Points to an msqid_ds structure. This structure is used only with the
      IPC_STAT and IPC_SET commands. With IPC_STAT, the results of the query
      are copied to this structure.  With IPC_SET, the values in this
      structure are used to set the corresponding fields in the msqid_ds
      structure associated with the message queue ID. In either case, the
      calling process must have allocated the structure before making the
      call.

DESCRIPTION
  The msgctl() function allows a process to query or set the contents of the
  msqid_ds structure associated with the specified message queue ID. It also
  allows a process to remove the message queue ID and its associated msqid_ds
  structure.  The cmd value determines which operation is performed.

  The IPC_SET command uses the user-supplied contents of the buf structure to
  set the following members of the msqid_ds structure associated with the
  message queue ID:

  msg_perm.uid
      The owner's user ID.

  msg_perm.gid
      The owner's group ID.

  msg_perm.mode
      The access modes for the queue. Only the low-order nine bits are set.

  msg_qbytes
      The maximum number of bytes on the queue.

  msg_ctime
      The time of the last successful IPC_SET operation.

RETURN VALUES
  Upon successful completion, msgctl() returns a value of 0 (zero).
  Otherwise, a value of -1 is returned and errno is set to indicate the
  error.

ERRORS
  The msgctl() function sets errno to the specified values for the following
  conditions:

  [EACCES]
      The cmd parameter is IPC_STAT, but the calling process does not have
      read permission.

  [EFAULT]
      [Tru64 UNIX]  The cmd parameter is IPC_STAT or IPC_SET, and an error
      occurred in accessing the buf structure.

  [EINVAL]
      The msqid parameter is not a valid message queue ID, or the cmd
      parameter is not a valid command.

  [EPERM]
      One of the following occurred:

	·  The cmd parameter is equal to either IPC_RMID or IPC_SET, and the
	   calling process does not have appropriate privilege.

	·  The cmd parameter is equal to IPC_SET, and an attempt is being
	   made to increase the value of the msg_qbytes parameter when the
	   calling process does not have the superuser privilege.

SEE ALSO
  Functions: msgget(2), msgrcv(2), msgsnd(2)

  Data Structures: msqid_ds(4)

  Standards: standards(5)

Index for Section 2

Alphabetical listing for M

Top of page