IPnom Home • Manuals • FreeBSD

 FreeBSD Man Pages

Man Sections:Commands (1)System Calls (2)Library Functions (3)Device Drivers (4)File Formats (5)Miscellaneous (7)System Utilities (8)
Keyword Live Search (10 results max):
 Type in part of a command in the search box.
 


msgctl(3)

NAME

     msgctl -- message control operations


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

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

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


DESCRIPTION

     The msgctl() system call performs some control operations on the message
     queue specified by msqid.

     Each message queue has a data structure associated with it, parts of
     which may be altered by msgctl() and parts of which determine the actions
     of msgctl().  The data structure is defined in <sys/msg.h> and contains
     (amongst others) the following members:

     struct msqid_ds {
	     struct  ipc_perm msg_perm;      /* msg queue permission bits */
	     struct  msg *msg_first; /* first message in the queue */
	     struct  msg *msg_last;  /* last message in the queue */
	     u_long  msg_cbytes;     /* number of bytes in use on the queue */
	     u_long  msg_qnum;	     /* number of msgs in the queue */
	     u_long  msg_qbytes;     /* max # of bytes on the queue */
	     pid_t   msg_lspid;      /* pid of last msgsnd() */
	     pid_t   msg_lrpid;      /* pid of last msgrcv() */
	     time_t  msg_stime;      /* time of last msgsnd() */
	     long    msg_pad1;
	     time_t  msg_rtime;      /* time of last msgrcv() */
	     long    msg_pad2;
	     time_t  msg_ctime;      /* time of last msgctl() */
	     long    msg_pad3;
	     long    msg_pad4[4];
     };

     The ipc_perm structure used inside the shmid_ds structure is defined in
     <sys/ipc.h> and looks like this:

     struct ipc_perm {
	     ushort  cuid;   /* creator user id */
	     ushort  cgid;   /* creator group id */
	     ushort  uid;    /* user id */
	     ushort  gid;    /* group id */
	     ushort  mode;   /* r/w permission */
	     ushort  seq;    /* sequence # (to generate unique msg/sem/shm id) */
	     key_t   key;    /* user specified msg/sem/shm key */
     };

     The operation to be performed by msgctl() is specified in cmd and is one
     of:

		user id equal to either msg_perm.cuid or msg_perm.uid in the
		data structure associated with the message queue.  The value
		of msg_qbytes can only be increased by the super-user.	Values
		for msg_qbytes that exceed the system limit (MSGMNB from
		<sys/msg.h>) are silently truncated to that limit.

     IPC_RMID	Remove the message queue specified by msqid and destroy the
		data associated with it.  Only the super-user or a process
		with an effective uid equal to the msg_perm.cuid or
		msg_perm.uid values in the data structure associated with the
		queue can do this.

     The permission to read from or write to a message queue (see msgsnd(3)
     and msgrcv(3)) is determined by the msg_perm.mode field in the same way
     as is done with files (see chmod(2)), but the effective uid can match
     either the msg_perm.cuid field or the msg_perm.uid field, and the effec-
     tive gid can match either msg_perm.cgid or msg_perm.gid.


RETURN VALUES

     The msgctl() function returns the value 0 if successful; otherwise the
     value -1 is returned and the global variable errno is set to indicate the
     error.


ERRORS

     The msgctl() function will fail if:

     [EPERM]		The cmd argument is equal to IPC_SET or IPC_RMID and
			the caller is not the super-user, nor does the effec-
			tive uid match either the msg_perm.uid or
			msg_perm.cuid fields of the data structure associated
			with the message queue.

			An attempt is made to increase the value of msg_qbytes
			through IPC_SET but the caller is not the super-user.

     [EACCES]		The command is IPC_STAT and the caller has no read
			permission for this message queue.

     [EINVAL]		The msqid argument is not a valid message queue iden-
			tifier.

			cmd is not a valid command.

     [EFAULT]		The buf argument specifies an invalid address.


SEE ALSO

     msgget(3), msgrcv(3), msgsnd(3)


HISTORY

     Message queues appeared in the first release of AT&T System V UNIX.

FreeBSD 5.4		       November 24, 1997		   FreeBSD 5.4

SPONSORED LINKS




Man(1) output converted with man2html , sed , awk