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