]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 Giorgio Ciucci <giorgio@crcc.it> |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
4 | .\" |
5 | .\" Added correction due to Nick Duffek <nsd@bbc.com>, aeb, 960426 | |
6 | .\" Modified Wed Nov 6 04:00:31 1996 by Eric S. Raymond <esr@thyrsus.com> | |
c11b1abf | 7 | .\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk.manpages@gmail.com> |
fea681da | 8 | .\" Removed EIDRM from errors - that can't happen... |
c11b1abf | 9 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 10 | .\" Added notes on capability requirements |
c11b1abf | 11 | .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
c952e226 MK |
12 | .\" Language and formatting clean-ups |
13 | .\" Added notes on /proc files | |
fea681da | 14 | .\" |
45186a5d | 15 | .TH MSGGET 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da | 16 | .SH NAME |
47f065d6 | 17 | msgget \- get a System V message queue identifier |
2c6b463e AC |
18 | .SH LIBRARY |
19 | Standard C library | |
8fc3b2cf | 20 | .RI ( libc ", " \-lc ) |
fea681da MK |
21 | .SH SYNOPSIS |
22 | .nf | |
2fadbfb5 | 23 | .B #include <sys/msg.h> |
dbfe9c70 | 24 | .PP |
34e8ac03 | 25 | .BI "int msgget(key_t " key ", int " msgflg ); |
ab04533a | 26 | .fi |
fea681da | 27 | .SH DESCRIPTION |
c952e226 MK |
28 | The |
29 | .BR msgget () | |
efbfd7ec | 30 | system call returns the System\ V message queue identifier associated |
fea681da MK |
31 | with the value of the |
32 | .I key | |
33 | argument. | |
f8ac3de3 MK |
34 | It may be used either to obtain the identifier of a previously created |
35 | message queue (when | |
36 | .I msgflg | |
37 | is zero and | |
38 | .I key | |
39 | does not have the value | |
40 | .BR IPC_PRIVATE ), | |
41 | or to create a new set. | |
d934a28c | 42 | .PP |
fea681da MK |
43 | A new message queue is created if |
44 | .I key | |
45 | has the value | |
46 | .B IPC_PRIVATE | |
47 | or | |
48 | .I key | |
49 | isn't | |
50 | .BR IPC_PRIVATE , | |
51 | no message queue with the given key | |
0daa9e92 | 52 | .I key |
fea681da MK |
53 | exists, and |
54 | .B IPC_CREAT | |
c952e226 MK |
55 | is specified in |
56 | .IR msgflg . | |
57 | .PP | |
58 | If | |
fea681da | 59 | .I msgflg |
c952e226 | 60 | specifies both |
fea681da MK |
61 | .B IPC_CREAT |
62 | and | |
63 | .B IPC_EXCL | |
64 | and a message queue already exists for | |
c952e226 MK |
65 | .IR key , |
66 | then | |
67 | .BR msgget () | |
c13182ef | 68 | fails with |
c952e226 MK |
69 | .I errno |
70 | set to | |
71 | .BR EEXIST . | |
c13182ef | 72 | (This is analogous to the effect of the combination |
c952e226 MK |
73 | .B O_CREAT | O_EXCL |
74 | for | |
75 | .BR open (2).) | |
fea681da | 76 | .PP |
c952e226 | 77 | Upon creation, the least significant bits of the argument |
fea681da | 78 | .I msgflg |
c952e226 | 79 | define the permissions of the message queue. |
fea681da | 80 | These permission bits have the same format and semantics |
c13182ef | 81 | as the permissions specified for the |
c952e226 MK |
82 | .I mode |
83 | argument of | |
84 | .BR open (2). | |
85 | (The execute permissions are not used.) | |
fea681da MK |
86 | .PP |
87 | If a new message queue is created, | |
c952e226 | 88 | then its associated data structure |
1176900f | 89 | .I msqid_ds |
c952e226 MK |
90 | (see |
91 | .BR msgctl (2)) | |
d9bfdb9c | 92 | is initialized as follows: |
3ed6ea8d | 93 | .IP \(bu 2 |
c952e226 | 94 | .I msg_perm.cuid |
fea681da | 95 | and |
c952e226 | 96 | .I msg_perm.uid |
499d62f2 | 97 | are set to the effective user ID of the calling process. |
3ed6ea8d | 98 | .IP \(bu |
c952e226 | 99 | .I msg_perm.cgid |
fea681da | 100 | and |
c952e226 | 101 | .I msg_perm.gid |
499d62f2 | 102 | are set to the effective group ID of the calling process. |
3ed6ea8d | 103 | .IP \(bu |
c952e226 MK |
104 | The least significant 9 bits of |
105 | .I msg_perm.mode | |
106 | are set to the least significant 9 bits of | |
fea681da | 107 | .IR msgflg . |
3ed6ea8d | 108 | .IP \(bu |
c952e226 MK |
109 | .IR msg_qnum , |
110 | .IR msg_lspid , | |
111 | .IR msg_lrpid , | |
a797afac | 112 | .IR msg_stime , |
fea681da | 113 | and |
c952e226 | 114 | .I msg_rtime |
fea681da | 115 | are set to 0. |
3ed6ea8d | 116 | .IP \(bu |
c952e226 | 117 | .I msg_ctime |
fea681da | 118 | is set to the current time. |
3ed6ea8d | 119 | .IP \(bu |
c952e226 | 120 | .I msg_qbytes |
fea681da MK |
121 | is set to the system limit |
122 | .BR MSGMNB . | |
123 | .PP | |
c952e226 | 124 | If the message queue already exists the permissions are |
fea681da MK |
125 | verified, and a check is made to see if it is marked for |
126 | destruction. | |
47297adb | 127 | .SH RETURN VALUE |
9862ec0c MK |
128 | On success, |
129 | .BR msgget () | |
130 | returns the message queue identifier (a nonnegative integer). | |
131 | On failure, \-1 is returned, and | |
c952e226 | 132 | .I errno |
9862ec0c | 133 | is set to indicate the error. |
fea681da | 134 | .SH ERRORS |
89b3c6b8 | 135 | .TP |
fea681da MK |
136 | .B EACCES |
137 | A message queue exists for | |
138 | .IR key , | |
139 | but the calling process does not have permission to access the queue, | |
140 | and does not have the | |
0daa9e92 | 141 | .B CAP_IPC_OWNER |
3294109d | 142 | capability in the user namespace that governs its IPC namespace. |
fea681da MK |
143 | .TP |
144 | .B EEXIST | |
fea681da MK |
145 | .B IPC_CREAT |
146 | and | |
1ae6b2c7 | 147 | .B IPC_EXCL |
85889360 MK |
148 | were specified in |
149 | .IR msgflg , | |
150 | but a message queue already exists for | |
151 | .IR key . | |
fea681da MK |
152 | .TP |
153 | .B ENOENT | |
154 | No message queue exists for | |
155 | .I key | |
156 | and | |
157 | .I msgflg | |
c952e226 | 158 | did not specify |
fea681da MK |
159 | .BR IPC_CREAT . |
160 | .TP | |
161 | .B ENOMEM | |
c952e226 MK |
162 | A message queue has to be created but the system does not have enough |
163 | memory for the new data structure. | |
fea681da MK |
164 | .TP |
165 | .B ENOSPC | |
166 | A message queue has to be created but the system limit for the maximum | |
167 | number of message queues | |
168 | .RB ( MSGMNI ) | |
169 | would be exceeded. | |
3113c7f3 | 170 | .SH STANDARDS |
c33c7b9a | 171 | POSIX.1-2001, POSIX.1-2008, SVr4. |
fea681da MK |
172 | .SH NOTES |
173 | .B IPC_PRIVATE | |
174 | isn't a flag field but a | |
c952e226 | 175 | .I key_t |
fea681da MK |
176 | type. |
177 | If this special value is used for | |
178 | .IR key , | |
c952e226 | 179 | the system call ignores everything but the least significant 9 bits of |
fea681da MK |
180 | .I msgflg |
181 | and creates a new message queue (on success). | |
182 | .PP | |
183 | The following is a system limit on message queue resources affecting a | |
c952e226 | 184 | .BR msgget () |
fea681da | 185 | call: |
89b3c6b8 | 186 | .TP |
fea681da | 187 | .B MSGMNI |
a75f73c2 MK |
188 | System-wide limit on the number of message queues. |
189 | Before Linux 3.19, | |
190 | .\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973 | |
191 | the default value for this limit was calculated using a formula | |
192 | based on available system memory. | |
193 | Since Linux 3.19, the default value is 32,000. | |
194 | On Linux, this limit can be read and modified via | |
195 | .IR /proc/sys/kernel/msgmni . | |
c634028a | 196 | .SS Linux notes |
3d565ddf | 197 | Until version 2.3.20, Linux would return |
0daa9e92 | 198 | .B EIDRM |
682edefb | 199 | for a |
4fb31341 MK |
200 | .BR msgget () |
201 | on a message queue scheduled for deletion. | |
fea681da | 202 | .SH BUGS |
682edefb | 203 | The name choice |
0daa9e92 | 204 | .B IPC_PRIVATE |
9091595d MK |
205 | was perhaps unfortunate, |
206 | .B IPC_NEW | |
fea681da | 207 | would more clearly show its function. |
47297adb | 208 | .SH SEE ALSO |
fea681da MK |
209 | .BR msgctl (2), |
210 | .BR msgrcv (2), | |
211 | .BR msgsnd (2), | |
212 | .BR ftok (3), | |
a9b305d6 | 213 | .BR capabilities (7), |
2c5e151c | 214 | .BR mq_overview (7), |
343cdc5a | 215 | .BR sysvipc (7) |