msgctl

MSGCTL(2)		  Linux Programmer’s Manual		    MSGCTL(2)



NAME
       msgctl - message control operations

SYNOPSIS
       #include <sys/types.h>
       #include <sys/ipc.h>
       #include <sys/msg.h>

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

DESCRIPTION
       This  function  performs the control operation specified by cmd on the
       message queue with identifier msqid.  Legal values for cmd are:

       IPC_STAT
	      Copy info from the message queue data structure associated with
	      msqid  into  the	structure pointed to by buf.  The caller must
	      have read permission on the message queue.

       IPC_SET
	      Write the values of some	members	 of  the  msqid_ds  structure
	      pointed to by buf to the message queue data structure, updating
	      also its msg_ctime member.  The following members of the struc-
	      ture can be updated:

		   msg_perm.uid
		   msg_perm.gid
		   msg_perm.mode  /* only lowest 9-bits */
		   msg_qbytes

	      The  calling  process  must  have	 appropriate (probably, root)
	      privileges or its effective user-ID must be that of the creator
	      (msg_perm.cuid)  or  owner (msg_perm.uid) of the message queue.
	      Appropriate (probably, root) privileges are required  to	raise
	      the msg_qbytes value beyond the system parameter MSGMNB.

       IPC_RMID
	      Immediately  remove  the	message queue and its associated data
	      structure, awakening all waiting reader  and  writer  processes
	      (with  an	 error	return	and errno set to EIDRM).  The calling
	      process must have appropriate (probably,	root)  privileges  or
	      its  effective  user-ID  must  be either that of the creator or
	      owner of the message queue.

RETURN VALUE
       On success, the return value will be 0, otherwise -1 with errno	indi-
       cating the error.

ERRORS
       On failure, errno is set to one of the following:

       EACCES	  The  argument cmd is equal to IPC_STAT but the calling pro-
		  cess does not have read permission  on  the  message	queue
		  msqid.

       EFAULT	  The argument cmd has the value IPC_SET or IPC_STAT, but the
		  address pointed to by buf isn’t accessible.

       EIDRM	  The message queue was removed.

       EINVAL	  Invalid value for cmd or msqid.

       EPERM	  The argument cmd has the value IPC_SET or IPC_RMID, but the
		  calling  process has insufficient privileges to execute the
		  command.

NOTES
       The IPC_INFO, MSG_STAT and MSG_INFO control  calls  are	used  by  the
       ipcs(8) program to provide information on allocated resources.  In the
       future these may be modified as needed or moved to a proc file  system
       interface.

       Various	fields	in  a struct msqid_ds were shorts under Linux 2.2 and
       have become longs under Linux 2.4. To take advantage of this, a recom-
       pilation under glibc-2.1.91 or later should suffice.  (The kernel dis-
       tinguishes old and new calls by a IPC_64 flag in cmd.)

CONFORMING TO
       SVr4, SVID.  SVID does not document the EIDRM error condition.

SEE ALSO
       ipc(5), msgget(2), msgsnd(2), msgrcv(2)



Linux 2.4.1			  2001-02-18			    MSGCTL(2)