X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man2%2Fmsgctl.2;h=507c21d0219e94a0a1219bc90908b1f1eabdf0fd;hb=9bfa575a6b9a784ddef194def5e2050f26543b02;hp=3f7ad9c6857a40e6b3de4031d733e84c7b9cbe75;hpb=930152530cc71f82cb6292416eda45750c6dba9c;p=thirdparty%2Fman-pages.git diff --git a/man2/msgctl.2 b/man2/msgctl.2 index 3f7ad9c685..507c21d021 100644 --- a/man2/msgctl.2 +++ b/man2/msgctl.2 @@ -33,36 +33,38 @@ .\" 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 2012-05-31 "Linux" "Linux Programmer's Manual" +.TH MSGCTL 2 2020-04-11 "Linux" "Linux Programmer's Manual" .SH NAME -msgctl \- message control operations +msgctl \- System V message control operations .SH SYNOPSIS .nf .B #include .B #include .B #include - +.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 message queue with identifier +on the System\ V message queue with identifier .IR msqid . .PP The .I msqid_ds data structure is defined in \fI\fP as follows: -.nf +.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 last change */ + time_t msg_ctime; /* Creation time/time of last + modification via msgctl() */ unsigned long __msg_cbytes; /* Current number of bytes in queue (nonstandard) */ msgqnum_t msg_qnum; /* Current number of messages @@ -72,8 +74,51 @@ struct msqid_ds { pid_t msg_lspid; /* PID of last msgsnd(2) */ pid_t msg_lrpid; /* PID of last msgrcv(2) */ }; +.EE .in -.fi +.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_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. +.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. .PP The .I ipc_perm @@ -81,8 +126,8 @@ structure is defined as follows (the highlighted fields are settable using .BR IPC_SET ): .PP -.nf .in +4n +.EX struct ipc_perm { key_t __key; /* Key supplied to msgget(2) */ uid_t \fBuid\fP; /* Effective UID of owner */ @@ -92,8 +137,26 @@ struct ipc_perm { unsigned short \fBmode\fP; /* Permissions */ unsigned short __seq; /* Sequence number */ }; +.EE .in -.fi +.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 @@ -129,7 +192,7 @@ or creator .RI ( msg_perm.cuid ) of the message queue, or the caller must be privileged. Appropriate privilege (Linux: the -.B CAP_IPC_RESOURCE +.B CAP_SYS_RESOURCE capability) is required to raise the .I msg_qbytes value beyond the system parameter @@ -145,9 +208,12 @@ set to 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)" -Returns information about system-wide message queue limits and +Return information about system-wide message queue limits and parameters in the structure pointed to by .IR buf . This structure is of type @@ -158,9 +224,9 @@ defined in if the .B _GNU_SOURCE feature test macro is defined: -.nf +.IP .in +4n - +.EX struct msginfo { int msgpool; /* Size in kibibytes of buffer pool used to hold message data; @@ -182,9 +248,9 @@ struct msginfo { /* Maximum number of segments; unused within kernel */ }; - +.EE .in -.fi +.IP The .IR msgmni , .IR msgmax , @@ -197,7 +263,7 @@ files of the same name; see for details. .TP .BR MSG_INFO " (Linux-specific)" -Returns a +Return a .I msginfo structure containing the same information as for .BR IPC_INFO , @@ -214,7 +280,7 @@ field returns the total number of bytes in all messages in all queues on the system. .TP .BR MSG_STAT " (Linux-specific)" -Returns a +Return a .I msqid_ds structure as for .BR IPC_STAT . @@ -223,6 +289,19 @@ However, the 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 , @@ -239,12 +318,16 @@ 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 error, \-1 is returned with .I errno indicating the error. @@ -264,7 +347,7 @@ 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. +capability in the user namespace that governs its IPC namespace. .TP .B EFAULT The argument @@ -305,11 +388,22 @@ or the owner (as found in .IR msg_perm.uid ) of the message queue, -and the process is not privileged (Linux: it does not have the +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 -SVr4, POSIX.1-2001. +POSIX.1-2001, POSIX.1-2008, SVr4. .\" SVID does not document the EIDRM error condition. .SH NOTES The inclusion of @@ -324,7 +418,7 @@ Applications intended to be portable to such old systems may need to include these header files. .\" Like Linux, the FreeBSD man pages still document .\" the inclusion of these header files. - +.PP The .BR IPC_INFO , .B MSG_STAT @@ -333,9 +427,10 @@ and 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 /proc file system -interface. - +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 @@ -355,4 +450,4 @@ flag in .BR msgsnd (2), .BR capabilities (7), .BR mq_overview (7), -.BR svipc (7) +.BR sysvipc (7)