unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



msgctl(2)							    msgctl(2)



NAME

  msgctl - Performs message control operations

SYNOPSIS

  #include <&lt;sys/msg.h>&gt;

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

  Application developers might want to specify #include	statements for
  <&lt;sys/types.h>&gt;	and <&lt;sys/ipc.h>&gt;	before the one for <&lt;sys/msg.h>&gt; if programs
  are being developed for multiple platforms. The additional #include state-
  ments	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 stan-
  dards.

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 indus-
  try 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 mes-
		      sage 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 asso-
		      ciated msqid_ds structure.  This operation is
		      restricted.  The effective user ID of the	calling	pro-
		      cess must	be equal to that of superuser or equal to the
		      value of msg_perm.uid or msg_perm.cuid in	the associ-
		      ated 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 allo-
	    cated 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).  Other-
  wise,	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.


SEE ALSO

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

  Data Structures: msqid_ds(4)

  Standards: standards(5)