Debian Codegraph @

upstream/debian-unstable/man2/msgget.2

raw
1 .\" Copyright 1993, Giorgio Ciucci <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH msgget 2 2026-02-11 "Linux man-pages 6.18"
7 .SH NAME
8 msgget \- get a System V message queue identifier
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <sys/msg.h>
15 .P
16 .BI "int msgget(key_t " key ", int " msgflg );
17 .fi
18 .SH DESCRIPTION
19 The
20 .BR msgget ()
21 system call returns the System\ V message queue identifier associated
22 with the value of the
23 .I key
24 argument.
25 It may be used either to obtain the identifier of a previously created
26 message queue (when
27 .I msgflg
28 is zero and
29 .I key
30 does not have the value
31 .BR IPC_PRIVATE ),
32 or to create a new set.
33 .P
34 A new message queue is created if
35 .I key
36 has the value
37 .B IPC_PRIVATE
38 or
39 .I key
40 isn't
41 .BR IPC_PRIVATE ,
42 no message queue with the given key
43 .I key
44 exists, and
45 .B IPC_CREAT
46 is specified in
47 .IR msgflg .
48 .P
49 If
50 .I msgflg
51 specifies both
52 .B IPC_CREAT
53 and
54 .B IPC_EXCL
55 and a message queue already exists for
56 .IR key ,
57 then
58 .BR msgget ()
59 fails with
60 .I errno
61 set to
62 .BR EEXIST .
63 (This is analogous to the effect of the combination
64 .B O_CREAT | O_EXCL
65 for
66 .BR open (2).)
67 .P
68 Upon creation, the least significant bits of the argument
69 .I msgflg
70 define the permissions of the message queue.
71 These permission bits have the same format and semantics
72 as the permissions specified for the
73 .I mode
74 argument of
75 .BR open (2).
76 (The execute permissions are not used.)
77 .P
78 If a new message queue is created,
79 then its associated data structure
80 .I msqid_ds
81 (see
82 .BR msgctl (2))
83 is initialized as follows:
84 .IP \[bu] 3
85 .I msg_perm.cuid
86 and
87 .I msg_perm.uid
88 are set to the effective user ID of the calling process.
89 .IP \[bu]
90 .I msg_perm.cgid
91 and
92 .I msg_perm.gid
93 are set to the effective group ID of the calling process.
94 .IP \[bu]
95 The least significant 9 bits of
96 .I msg_perm.mode
97 are set to the least significant 9 bits of
98 .IR msgflg .
99 .IP \[bu]
100 .IR msg_qnum ,
101 .IR msg_lspid ,
102 .IR msg_lrpid ,
103 .IR msg_stime ,
104 and
105 .I msg_rtime
106 are set to 0.
107 .IP \[bu]
108 .I msg_ctime
109 is set to the current time.
110 .IP \[bu]
111 .I msg_qbytes
112 is set to the system limit
113 .BR MSGMNB .
114 .P
115 If the message queue already exists the permissions are
116 verified, and a check is made to see if it is marked for
117 destruction.
118 .SH RETURN VALUE
119 On success,
120 .BR msgget ()
121 returns the message queue identifier (a nonnegative integer).
122 On failure, \-1 is returned, and
123 .I errno
124 is set to indicate the error.
125 .SH ERRORS
126 .TP
127 .B EACCES
128 A message queue exists for
129 .IR key ,
130 but the calling process does not have permission to access the queue,
131 and does not have the
132 .B CAP_IPC_OWNER
133 capability in the user namespace that governs its IPC namespace.
134 .TP
135 .B EEXIST
136 .B IPC_CREAT
137 and
138 .B IPC_EXCL
139 were specified in
140 .IR msgflg ,
141 but a message queue already exists for
142 .IR key .
143 .TP
144 .B ENOENT
145 No message queue exists for
146 .I key
147 and
148 .I msgflg
149 did not specify
150 .BR IPC_CREAT .
151 .TP
152 .B ENOMEM
153 A message queue has to be created but the system does not have enough
154 memory for the new data structure.
155 .TP
156 .B ENOSPC
157 A message queue has to be created but the system limit for the maximum
158 number of message queues
159 .RB ( MSGMNI )
160 would be exceeded.
161 .SH STANDARDS
162 POSIX.1-2024 XSI.
163 .SH HISTORY
164 SVr4,
165 SUSv1,
166 POSIX.1-2001 XSI.
167 .SS Linux
168 Until Linux 2.3.20, Linux would return
169 .B EIDRM
170 for a
171 .BR msgget ()
172 on a message queue scheduled for deletion.
173 .SH NOTES
174 .B IPC_PRIVATE
175 isn't a flag field but a
176 .I key_t
177 type.
178 If this special value is used for
179 .IR key ,
180 the system call ignores everything but the least significant 9 bits of
181 .I msgflg
182 and creates a new message queue (on success).
183 .P
184 The following is a system limit on message queue resources affecting a
185 .BR msgget ()
186 call:
187 .TP
188 .B MSGMNI
189 System-wide limit on the number of message queues.
190 Before Linux 3.19,
191 .\" commit 0050ee059f7fc86b1df2527aaa14ed5dc72f9973
192 the default value for this limit was calculated using a formula
193 based on available system memory.
194 Since Linux 3.19, the default value is 32,000.
195 On Linux, this limit can be read and modified via
196 .IR /proc/sys/kernel/msgmni .
197 .SH BUGS
198 The name choice
199 .B IPC_PRIVATE
200 was perhaps unfortunate,
201 .B IPC_NEW
202 would more clearly show its function.
203 .SH SEE ALSO
204 .BR msgctl (2),
205 .BR msgrcv (2),
206 .BR msgsnd (2),
207 .BR ftok (3),
208 .BR capabilities (7),
209 .BR mq_overview (7),
210 .BR sysvipc (7)