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