man2/shmget.2

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