| .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) |
| .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| msgctl \- System V message control operations |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/ipc.h> |
| .B #include <sys/msg.h> |
| .PP |
| .BI "int msgctl(int " msqid ", int " cmd ", struct msqid_ds *" buf ); |
| .fi |
| .SH DESCRIPTION |
| .BR msgctl () |
| performs the control operation specified by |
| .I cmd |
| on the System\ V message queue with identifier |
| .IR msqid . |
| .PP |
| The |
| .I msqid_ds |
| data structure is defined in \fI<sys/msg.h>\fP as follows: |
| .PP |
| .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 |
| .PP |
| The fields of the |
| .I msgid_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 () |
| .BR 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. |
| .PP |
| The |
| .I ipc_perm |
| structure is defined as follows |
| (the highlighted fields are settable using |
| .BR IPC_SET ): |
| .PP |
| .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 |
| .PP |
| 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 |
| .PP |
| Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. |
| .PP |
| Valid values for |
| .I cmd |
| 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 |
| .IR msqid |
| meaning that any user can employ this operation (just as any user may read |
| .IR /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 . |
| .PP |
| On failure, \-1 is returned and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EACCES |
| The argument |
| .I cmd |
| 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 cmd |
| 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 cmd |
| 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 cmd |
| 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 CONFORMING TO |
| POSIX.1-2001, POSIX.1-2008, SVr4. |
| .\" SVID does not document the EIDRM error condition. |
| .SH NOTES |
| The inclusion of |
| .I <sys/ipc.h> |
| isn't required on Linux or by any version of POSIX. |
| However, |
| some old implementations required the inclusion of this header file, |
| and the SVID also documented its inclusion. |
| Applications intended to be portable to such old systems may need |
| to include this header file. |
| .\" Like Linux, the FreeBSD man pages still document |
| .\" the inclusion of this header file. |
| .PP |
| 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. |
| .PP |
| 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 cmd .) |
| .SH SEE ALSO |
| .BR msgget (2), |
| .BR msgrcv (2), |
| .BR msgsnd (2), |
| .BR capabilities (7), |
| .BR mq_overview (7), |
| .BR sysvipc (7) |