Index for Section 2

Alphabetical listing for M

Bottom of page

msgctl(2)
NAME
  msgctl - Performs message control operations

SYNOPSIS
  #include <sys/msg.h>

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

  Application developers may 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():  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 a 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 msgctl() operation that changed the
	    structure.

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]   The cmd parameter is equal to either IPC_RMID or IPC_SET, and the
	    calling process does not have appropriate privilege.

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

RELATED INFORMATION
  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