| 1 |
.\" Copyright 1993, Luigi P. Bai <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH shmget 2 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
shmget \- allocates a System V shared memory segment |
| 9 |
.SH LIBRARY |
| 10 |
Standard C library |
| 11 |
.RI ( libc ,\~ \-lc ) |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
.B #include <sys/shm.h> |
| 15 |
.P |
| 16 |
.BI "int shmget(key_t " key ", size_t " size ", int " shmflg ); |
| 17 |
.fi |
| 18 |
.SH DESCRIPTION |
| 19 |
.BR shmget () |
| 20 |
returns the identifier of the System\ V shared memory segment |
| 21 |
associated with the value of the argument |
| 22 |
.IR key . |
| 23 |
It may be used either to obtain the identifier of a previously created |
| 24 |
shared memory segment (when |
| 25 |
.I shmflg |
| 26 |
is zero and |
| 27 |
.I key |
| 28 |
does not have the value |
| 29 |
.BR IPC_PRIVATE ), |
| 30 |
or to create a new set. |
| 31 |
.P |
| 32 |
A new shared memory segment, with size equal to the value of |
| 33 |
.I size |
| 34 |
rounded up to a multiple of |
| 35 |
.BR PAGE_SIZE , |
| 36 |
is created if |
| 37 |
.I key |
| 38 |
has the value |
| 39 |
.B IPC_PRIVATE |
| 40 |
or |
| 41 |
.I key |
| 42 |
isn't |
| 43 |
.BR IPC_PRIVATE , |
| 44 |
no shared memory segment corresponding to |
| 45 |
.I key |
| 46 |
exists, and |
| 47 |
.B IPC_CREAT |
| 48 |
is specified in |
| 49 |
.IR shmflg . |
| 50 |
.P |
| 51 |
If |
| 52 |
.I shmflg |
| 53 |
specifies both |
| 54 |
.B IPC_CREAT |
| 55 |
and |
| 56 |
.B IPC_EXCL |
| 57 |
and a shared memory segment already exists for |
| 58 |
.IR key , |
| 59 |
then |
| 60 |
.BR shmget () |
| 61 |
fails with |
| 62 |
.I errno |
| 63 |
set to |
| 64 |
.BR EEXIST . |
| 65 |
(This is analogous to the effect of the combination |
| 66 |
.B O_CREAT | O_EXCL |
| 67 |
for |
| 68 |
.BR open (2).) |
| 69 |
.P |
| 70 |
The value |
| 71 |
.I shmflg |
| 72 |
is composed of: |
| 73 |
.TP |
| 74 |
.B IPC_CREAT |
| 75 |
Create a new segment. |
| 76 |
If this flag is not used, then |
| 77 |
.BR shmget () |
| 78 |
will find the segment associated with |
| 79 |
.I key |
| 80 |
and check to see if |
| 81 |
the user has permission to access the segment. |
| 82 |
.TP |
| 83 |
.B IPC_EXCL |
| 84 |
This flag is used with |
| 85 |
.B IPC_CREAT |
| 86 |
to ensure that this call creates the segment. |
| 87 |
If the segment already exists, the call fails. |
| 88 |
.TP |
| 89 |
.BR SHM_HUGETLB " (since Linux 2.6)" |
| 90 |
Allocate the segment using "huge" pages. |
| 91 |
See the Linux kernel source file |
| 92 |
.I Documentation/admin\-guide/mm/hugetlbpage.rst |
| 93 |
for further information. |
| 94 |
.TP |
| 95 |
.B SHM_HUGE_2MB |
| 96 |
.TQ |
| 97 |
.BR SHM_HUGE_1GB " (since Linux 3.8)" |
| 98 |
.\" See https://lwn.net/Articles/533499/ |
| 99 |
Used in conjunction with |
| 100 |
.B SHM_HUGETLB |
| 101 |
to select alternative hugetlb page sizes (respectively, 2\ MB and 1\ GB) |
| 102 |
on systems that support multiple hugetlb page sizes. |
| 103 |
.IP |
| 104 |
More generally, the desired huge page size can be configured by encoding |
| 105 |
the base-2 logarithm of the desired page size in the six bits at the offset |
| 106 |
.BR SHM_HUGE_SHIFT . |
| 107 |
Thus, the above two constants are defined as: |
| 108 |
.IP |
| 109 |
.in +4n |
| 110 |
.EX |
| 111 |
#define SHM_HUGE_2MB (21 << SHM_HUGE_SHIFT) |
| 112 |
#define SHM_HUGE_1GB (30 << SHM_HUGE_SHIFT) |
| 113 |
.EE |
| 114 |
.in |
| 115 |
.IP |
| 116 |
For some additional details, |
| 117 |
see the discussion of the similarly named constants in |
| 118 |
.BR mmap (2). |
| 119 |
.TP |
| 120 |
.BR SHM_NORESERVE " (since Linux 2.6.15)" |
| 121 |
This flag serves the same purpose as the |
| 122 |
.BR mmap (2) |
| 123 |
.B MAP_NORESERVE |
| 124 |
flag. |
| 125 |
Do not reserve swap space for this segment. |
| 126 |
When swap space is reserved, one has the guarantee |
| 127 |
that it is possible to modify the segment. |
| 128 |
When swap space is not reserved one might get |
| 129 |
.B SIGSEGV |
| 130 |
upon a write |
| 131 |
if no physical memory is available. |
| 132 |
See also the discussion of the file |
| 133 |
.I /proc/sys/vm/overcommit_memory |
| 134 |
in |
| 135 |
.BR proc_sys_vm (5). |
| 136 |
.\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also |
| 137 |
.\" specified. |
| 138 |
.P |
| 139 |
In addition to the above flags, the least significant 9 bits of |
| 140 |
.I shmflg |
| 141 |
specify the permissions granted to the owner, group, and others. |
| 142 |
These bits have the same format, and the same |
| 143 |
meaning, as the |
| 144 |
.I mode |
| 145 |
argument of |
| 146 |
.BR open (2). |
| 147 |
Presently, execute permissions are not used by the system. |
| 148 |
.P |
| 149 |
When a new shared memory segment is created, |
| 150 |
its contents are initialized to zero values, and |
| 151 |
its associated data structure, |
| 152 |
.I shmid_ds |
| 153 |
(see |
| 154 |
.BR shmctl (2)), |
| 155 |
is initialized as follows: |
| 156 |
.IP \[bu] 3 |
| 157 |
.I shm_perm.cuid |
| 158 |
and |
| 159 |
.I shm_perm.uid |
| 160 |
are set to the effective user ID of the calling process. |
| 161 |
.IP \[bu] |
| 162 |
.I shm_perm.cgid |
| 163 |
and |
| 164 |
.I shm_perm.gid |
| 165 |
are set to the effective group ID of the calling process. |
| 166 |
.IP \[bu] |
| 167 |
The least significant 9 bits of |
| 168 |
.I shm_perm.mode |
| 169 |
are set to the least significant 9 bit of |
| 170 |
.IR shmflg . |
| 171 |
.IP \[bu] |
| 172 |
.I shm_segsz |
| 173 |
is set to the value of |
| 174 |
.IR size . |
| 175 |
.IP \[bu] |
| 176 |
.IR shm_lpid , |
| 177 |
.IR shm_nattch , |
| 178 |
.IR shm_atime , |
| 179 |
and |
| 180 |
.I shm_dtime |
| 181 |
are set to 0. |
| 182 |
.IP \[bu] |
| 183 |
.I shm_ctime |
| 184 |
is set to the current time. |
| 185 |
.P |
| 186 |
If the shared memory segment already exists, the permissions are |
| 187 |
verified, and a check is made to see if it is marked for destruction. |
| 188 |
.SH RETURN VALUE |
| 189 |
On success, a valid shared memory identifier is returned. |
| 190 |
On error, \-1 is returned, and |
| 191 |
.I errno |
| 192 |
is set to indicate the error. |
| 193 |
.SH ERRORS |
| 194 |
.TP |
| 195 |
.B EACCES |
| 196 |
The user does not have permission to access the |
| 197 |
shared memory segment, and does not have the |
| 198 |
.B CAP_IPC_OWNER |
| 199 |
capability in the user namespace that governs its IPC namespace. |
| 200 |
.TP |
| 201 |
.B EEXIST |
| 202 |
.B IPC_CREAT |
| 203 |
and |
| 204 |
.B IPC_EXCL |
| 205 |
were specified in |
| 206 |
.IR shmflg , |
| 207 |
but a shared memory segment already exists for |
| 208 |
.IR key . |
| 209 |
.TP |
| 210 |
.B EINVAL |
| 211 |
A new segment was to be created and |
| 212 |
.I size |
| 213 |
is less than |
| 214 |
.B SHMMIN |
| 215 |
or greater than |
| 216 |
.BR SHMMAX . |
| 217 |
.TP |
| 218 |
.B EINVAL |
| 219 |
A segment for the given |
| 220 |
.I key |
| 221 |
exists, but |
| 222 |
.I size |
| 223 |
is greater than the size |
| 224 |
of that segment. |
| 225 |
.TP |
| 226 |
.B ENFILE |
| 227 |
.\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp() |
| 228 |
The system-wide limit on the total number of open files has been reached. |
| 229 |
.TP |
| 230 |
.B ENOENT |
| 231 |
No segment exists for the given |
| 232 |
.IR key , |
| 233 |
and |
| 234 |
.B IPC_CREAT |
| 235 |
was not specified. |
| 236 |
.TP |
| 237 |
.B ENOMEM |
| 238 |
No memory could be allocated for segment overhead. |
| 239 |
.TP |
| 240 |
.B ENOSPC |
| 241 |
All possible shared memory IDs have been taken |
| 242 |
.RB ( SHMMNI ), |
| 243 |
or allocating a segment of the requested |
| 244 |
.I size |
| 245 |
would cause the system to exceed the system-wide limit on shared memory |
| 246 |
.RB ( SHMALL ). |
| 247 |
.TP |
| 248 |
.B EPERM |
| 249 |
The |
| 250 |
.B SHM_HUGETLB |
| 251 |
flag was specified, but the caller was not privileged (did not have the |
| 252 |
.B CAP_IPC_LOCK |
| 253 |
capability) |
| 254 |
and is not a member of the |
| 255 |
.I hugetlb_shm_group |
| 256 |
group; |
| 257 |
see the description of |
| 258 |
.I /proc/sys/vm/hugetlb_shm_group |
| 259 |
in |
| 260 |
.BR proc_sys_vm (5). |
| 261 |
.SH STANDARDS |
| 262 |
POSIX.1-2024. |
| 263 |
.P |
| 264 |
.B SHM_HUGETLB |
| 265 |
and |
| 266 |
.B SHM_NORESERVE |
| 267 |
are Linux extensions. |
| 268 |
.SH HISTORY |
| 269 |
POSIX.1-2001, SVr4. |
| 270 |
.\" SVr4 documents an additional error condition EEXIST. |
| 271 |
.SH NOTES |
| 272 |
.B IPC_PRIVATE |
| 273 |
isn't a flag field but a |
| 274 |
.I key_t |
| 275 |
type. |
| 276 |
If this special value is used for |
| 277 |
.IR key , |
| 278 |
the system call ignores all but the least significant 9 bits of |
| 279 |
.I shmflg |
| 280 |
and creates a new shared memory segment. |
| 281 |
.\" |
| 282 |
.SS Shared memory limits |
| 283 |
The following limits on shared memory segment resources affect the |
| 284 |
.BR shmget () |
| 285 |
call: |
| 286 |
.TP |
| 287 |
.B SHMALL |
| 288 |
System-wide limit on the total amount of shared memory, |
| 289 |
measured in units of the system page size. |
| 290 |
.IP |
| 291 |
On Linux, this limit can be read and modified via |
| 292 |
.IR /proc/sys/kernel/shmall . |
| 293 |
Since Linux 3.16, |
| 294 |
.\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31 |
| 295 |
the default value for this limit is: |
| 296 |
.IP |
| 297 |
.in +4n |
| 298 |
.EX |
| 299 |
ULONG_MAX - 2\[ha]24 |
| 300 |
.EE |
| 301 |
.in |
| 302 |
.IP |
| 303 |
The effect of this value |
| 304 |
(which is suitable for both 32-bit and 64-bit systems) |
| 305 |
is to impose no limitation on allocations. |
| 306 |
This value, rather than |
| 307 |
.BR ULONG_MAX , |
| 308 |
was chosen as the default to prevent some cases where historical |
| 309 |
applications simply raised the existing limit without first checking |
| 310 |
its current value. |
| 311 |
Such applications would cause the value to overflow if the limit was set at |
| 312 |
.BR ULONG_MAX . |
| 313 |
.IP |
| 314 |
From Linux 2.4 up to Linux 3.15, |
| 315 |
the default value for this limit was: |
| 316 |
.IP |
| 317 |
.in +4n |
| 318 |
.EX |
| 319 |
SHMMAX / PAGE_SIZE * (SHMMNI / 16) |
| 320 |
.EE |
| 321 |
.in |
| 322 |
.IP |
| 323 |
If |
| 324 |
.B SHMMAX |
| 325 |
and |
| 326 |
.B SHMMNI |
| 327 |
were not modified, then multiplying the result of this formula |
| 328 |
by the page size (to get a value in bytes) yielded a value of 8\ GB |
| 329 |
as the limit on the total memory used by all shared memory segments. |
| 330 |
.TP |
| 331 |
.B SHMMAX |
| 332 |
Maximum size in bytes for a shared memory segment. |
| 333 |
.IP |
| 334 |
On Linux, this limit can be read and modified via |
| 335 |
.IR /proc/sys/kernel/shmmax . |
| 336 |
Since Linux 3.16, |
| 337 |
.\" commit 060028bac94bf60a65415d1d55a359c3a17d5c31 |
| 338 |
the default value for this limit is: |
| 339 |
.IP |
| 340 |
.in +4n |
| 341 |
.EX |
| 342 |
ULONG_MAX - 2\[ha]24 |
| 343 |
.EE |
| 344 |
.in |
| 345 |
.IP |
| 346 |
The effect of this value |
| 347 |
(which is suitable for both 32-bit and 64-bit systems) |
| 348 |
is to impose no limitation on allocations. |
| 349 |
See the description of |
| 350 |
.B SHMALL |
| 351 |
for a discussion of why this default value (rather than |
| 352 |
.BR ULONG_MAX ) |
| 353 |
is used. |
| 354 |
.IP |
| 355 |
From Linux 2.2 up to Linux 3.15, the default value of |
| 356 |
this limit was 0x2000000 (32\ MiB). |
| 357 |
.IP |
| 358 |
Because it is not possible to map just part of a shared memory segment, |
| 359 |
the amount of virtual memory places another limit on the maximum size of a |
| 360 |
usable segment: |
| 361 |
for example, on i386 the largest segments that can be mapped have a |
| 362 |
size of around 2.8\ GB, and on x86-64 the limit is around 127 TB. |
| 363 |
.TP |
| 364 |
.B SHMMIN |
| 365 |
Minimum size in bytes for a shared memory segment: implementation |
| 366 |
dependent (currently 1 byte, though |
| 367 |
.B PAGE_SIZE |
| 368 |
is the effective minimum size). |
| 369 |
.TP |
| 370 |
.B SHMMNI |
| 371 |
System-wide limit on the number of shared memory segments. |
| 372 |
In Linux 2.2, the default value for this limit was 128; |
| 373 |
since Linux 2.4, the default value is 4096. |
| 374 |
.IP |
| 375 |
On Linux, this limit can be read and modified via |
| 376 |
.IR /proc/sys/kernel/shmmni . |
| 377 |
.\" Kernels between Linux 2.4.x and Linux 2.6.8 had an off-by-one error |
| 378 |
.\" that meant that we could create one more segment than SHMMNI -- MTK |
| 379 |
.\" This /proc file is not available in Linux 2.2 and earlier -- MTK |
| 380 |
.P |
| 381 |
The implementation has no specific limits for the per-process maximum |
| 382 |
number of shared memory segments |
| 383 |
.RB ( SHMSEG ). |
| 384 |
.SS Linux notes |
| 385 |
Until Linux 2.3.30, Linux would return |
| 386 |
.B EIDRM |
| 387 |
for a |
| 388 |
.BR shmget () |
| 389 |
on a shared memory segment scheduled for deletion. |
| 390 |
.SH BUGS |
| 391 |
The name choice |
| 392 |
.B IPC_PRIVATE |
| 393 |
was perhaps unfortunate, |
| 394 |
.B IPC_NEW |
| 395 |
would more clearly show its function. |
| 396 |
.SH EXAMPLES |
| 397 |
See |
| 398 |
.BR shmop (2). |
| 399 |
.SH SEE ALSO |
| 400 |
.BR memfd_create (2), |
| 401 |
.BR shmat (2), |
| 402 |
.BR shmctl (2), |
| 403 |
.BR shmdt (2), |
| 404 |
.BR ftok (3), |
| 405 |
.BR capabilities (7), |
| 406 |
.BR shm_overview (7), |
| 407 |
.BR sysvipc (7) |