diff options
Diffstat (limited to 'man/man2/msgctl.2')
| -rw-r--r-- | man/man2/msgctl.2 | 424 |
1 files changed, 424 insertions, 0 deletions
diff --git a/man/man2/msgctl.2 b/man/man2/msgctl.2 new file mode 100644 index 000000000..70f4d1cf8 --- /dev/null +++ b/man/man2/msgctl.2 @@ -0,0 +1,424 @@ +'\" t +.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) +.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Tue Oct 22 08:11:14 EDT 1996 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified Sun Feb 18 01:59:29 2001 by Andries E. Brouwer <aeb@cwi.nl> +.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added notes on CAP_IPC_OWNER requirement +.\" Modified, 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID +.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Language and formatting clean-ups +.\" Added msqid_ds and ipc_perm structure definitions +.\" 2005-08-02, mtk: Added IPC_INFO, MSG_INFO, MSG_STAT descriptions +.\" 2018-03-20, dbueso: Added MSG_STAT_ANY description. +.\" +.TH msgctl 2 (date) "Linux man-pages (unreleased)" +.SH NAME +msgctl \- System V message control operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/msg.h> +.P +.BI "int msgctl(int " msqid ", int " op ", struct msqid_ds *" buf ); +.fi +.SH DESCRIPTION +.BR msgctl () +performs the control operation specified by +.I op +on the System\ V message queue with identifier +.IR msqid . +.P +The +.I msqid_ds +data structure is defined in \fI<sys/msg.h>\fP as follows: +.P +.in +4n +.EX +struct msqid_ds { + struct ipc_perm msg_perm; /* Ownership and permissions */ + time_t msg_stime; /* Time of last msgsnd(2) */ + time_t msg_rtime; /* Time of last msgrcv(2) */ + time_t msg_ctime; /* Time of creation or last + modification by msgctl() */ + unsigned long msg_cbytes; /* # of bytes in queue */ + msgqnum_t msg_qnum; /* # number of messages in queue */ + msglen_t msg_qbytes; /* Maximum # of bytes in queue */ + pid_t msg_lspid; /* PID of last msgsnd(2) */ + pid_t msg_lrpid; /* PID of last msgrcv(2) */ +}; +.EE +.in +.P +The fields of the +.I msqid_ds +structure are as follows: +.TP 11 +.I msg_perm +This is an +.I ipc_perm +structure (see below) that specifies the access permissions on the message +queue. +.TP +.I msg_stime +Time of the last +.BR msgsnd (2) +system call. +.TP +.I msg_rtime +Time of the last +.BR msgrcv (2) +system call. +.TP +.I msg_ctime +Time of creation of queue or time of last +.BR msgctl () +.B IPC_SET +operation. +.TP +.I msg_cbytes +Number of bytes in all messages currently on the message queue. +This is a nonstandard Linux extension that is not specified in POSIX. +.TP +.I msg_qnum +Number of messages currently on the message queue. +.TP +.I msg_qbytes +Maximum number of bytes of message text allowed on the message +queue. +.TP +.I msg_lspid +ID of the process that performed the last +.BR msgsnd (2) +system call. +.TP +.I msg_lrpid +ID of the process that performed the last +.BR msgrcv (2) +system call. +.P +The +.I ipc_perm +structure is defined as follows +(the highlighted fields are settable using +.BR IPC_SET ): +.P +.in +4n +.EX +struct ipc_perm { + key_t __key; /* Key supplied to msgget(2) */ + uid_t \fBuid\fP; /* Effective UID of owner */ + gid_t \fBgid\fP; /* Effective GID of owner */ + uid_t cuid; /* Effective UID of creator */ + gid_t cgid; /* Effective GID of creator */ + unsigned short \fBmode\fP; /* Permissions */ + unsigned short __seq; /* Sequence number */ +}; +.EE +.in +.P +The least significant 9 bits of the +.I mode +field of the +.I ipc_perm +structure define the access permissions for the message queue. +The permission bits are as follows: +.TS +l l. +0400 Read by user +0200 Write by user +0040 Read by group +0020 Write by group +0004 Read by others +0002 Write by others +.TE +.P +Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. +.P +Valid values for +.I op +are: +.TP +.B IPC_STAT +Copy information from the kernel data structure associated with +.I msqid +into the +.I msqid_ds +structure pointed to by +.IR buf . +The caller must have read permission on the message queue. +.TP +.B IPC_SET +Write the values of some members of the +.I msqid_ds +structure pointed to by +.I buf +to the kernel data structure associated with this message queue, +updating also its +.I msg_ctime +member. +.IP +The following members of the structure are updated: +.IR msg_qbytes , +.IR msg_perm.uid , +.IR msg_perm.gid , +and (the least significant 9 bits of) +.IR msg_perm.mode . +.IP +The effective UID of the calling process must match the owner +.RI ( msg_perm.uid ) +or creator +.RI ( msg_perm.cuid ) +of the message queue, or the caller must be privileged. +Appropriate privilege (Linux: the +.B CAP_SYS_RESOURCE +capability) is required to raise the +.I msg_qbytes +value beyond the system parameter +.BR MSGMNB . +.TP +.B IPC_RMID +Immediately remove the message queue, +awakening all waiting reader and writer processes (with an error +return and +.I errno +set to +.BR EIDRM ). +The calling process must have appropriate privileges +or its effective user ID must be either that of the creator or owner +of the message queue. +The third argument to +.BR msgctl () +is ignored in this case. +.TP +.BR IPC_INFO " (Linux-specific)" +Return information about system-wide message queue limits and +parameters in the structure pointed to by +.IR buf . +This structure is of type +.I msginfo +(thus, a cast is required), +defined in +.I <sys/msg.h> +if the +.B _GNU_SOURCE +feature test macro is defined: +.IP +.in +4n +.EX +struct msginfo { + int msgpool; /* Size in kibibytes of buffer pool + used to hold message data; + unused within kernel */ + int msgmap; /* Maximum number of entries in message + map; unused within kernel */ + int msgmax; /* Maximum number of bytes that can be + written in a single message */ + int msgmnb; /* Maximum number of bytes that can be + written to queue; used to initialize + msg_qbytes during queue creation + (msgget(2)) */ + int msgmni; /* Maximum number of message queues */ + int msgssz; /* Message segment size; + unused within kernel */ + int msgtql; /* Maximum number of messages on all queues + in system; unused within kernel */ + unsigned short msgseg; + /* Maximum number of segments; + unused within kernel */ +}; +.EE +.in +.IP +The +.IR msgmni , +.IR msgmax , +and +.I msgmnb +settings can be changed via +.I /proc +files of the same name; see +.BR proc (5) +for details. +.TP +.BR MSG_INFO " (Linux-specific)" +Return a +.I msginfo +structure containing the same information as for +.BR IPC_INFO , +except that the following fields are returned with information +about system resources consumed by message queues: the +.I msgpool +field returns the number of message queues that currently exist +on the system; the +.I msgmap +field returns the total number of messages in all queues +on the system; and the +.I msgtql +field returns the total number of bytes in all messages +in all queues on the system. +.TP +.BR MSG_STAT " (Linux-specific)" +Return a +.I msqid_ds +structure as for +.BR IPC_STAT . +However, the +.I msqid +argument is not a queue identifier, but instead an index into +the kernel's internal array that maintains information about +all message queues on the system. +.TP +.BR MSG_STAT_ANY " (Linux-specific, since Linux 4.17)" +Return a +.I msqid_ds +structure as for +.BR MSG_STAT . +However, +.I msg_perm.mode +is not checked for read access for +.I msqid +meaning that any user can employ this operation (just as any user may read +.I /proc/sysvipc/msg +to obtain the same information). +.SH RETURN VALUE +On success, +.BR IPC_STAT , +.BR IPC_SET , +and +.B IPC_RMID +return 0. +A successful +.B IPC_INFO +or +.B MSG_INFO +operation returns the index of the highest used entry in the +kernel's internal array recording information about all +message queues. +(This information can be used with repeated +.B MSG_STAT +or +.B MSG_STAT_ANY +operations to obtain information about all queues on the system.) +A successful +.B MSG_STAT +or +.B MSG_STAT_ANY +operation returns the identifier of the queue whose index was given in +.IR msqid . +.P +On failure, \-1 is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EACCES +The argument +.I op +is equal to +.B IPC_STAT +or +.BR MSG_STAT , +but the calling process does not have read permission on the message queue +.IR msqid , +and does not have the +.B CAP_IPC_OWNER +capability in the user namespace that governs its IPC namespace. +.TP +.B EFAULT +The argument +.I op +has the value +.B IPC_SET +or +.BR IPC_STAT , +but the address pointed to by +.I buf +isn't accessible. +.TP +.B EIDRM +The message queue was removed. +.TP +.B EINVAL +Invalid value for +.I op +or +.IR msqid . +Or: for a +.B MSG_STAT +operation, the index value specified in +.I msqid +referred to an array slot that is currently unused. +.TP +.B EPERM +The argument +.I op +has the value +.B IPC_SET +or +.BR IPC_RMID , +but the effective user ID of the calling process is not the creator +(as found in +.IR msg_perm.cuid ) +or the owner +(as found in +.IR msg_perm.uid ) +of the message queue, +and the caller is not privileged (Linux: does not have the +.B CAP_SYS_ADMIN +capability). +.TP +.B EPERM +An attempt +.RB ( IPC_SET ) +was made to increase +.I msg_qbytes +beyond the system parameter +.BR MSGMNB , +but the caller is not privileged (Linux: does not have the +.B CAP_SYS_RESOURCE +capability). +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4. +.\" SVID does not document the EIDRM error condition. +.P +Various fields in the \fIstruct msqid_ds\fP were +typed as +.I short +under Linux 2.2 +and have become +.I long +under Linux 2.4. +To take advantage of this, +a recompilation under glibc-2.1.91 or later should suffice. +(The kernel distinguishes old and new calls by an +.B IPC_64 +flag in +.IR op .) +.SH NOTES +The +.BR IPC_INFO , +.BR MSG_STAT , +and +.B MSG_INFO +operations are used by the +.BR ipcs (1) +program to provide information on allocated resources. +In the future these may modified or moved to a +.I /proc +filesystem interface. +.SH SEE ALSO +.BR msgget (2), +.BR msgrcv (2), +.BR msgsnd (2), +.BR capabilities (7), +.BR mq_overview (7), +.BR sysvipc (7) |