original/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 2014-05-21 "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 .sp
  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 A new shared memory segment, with size equal to the value of
  55 .I size
  56 rounded up to a multiple of
  57 .BR PAGE_SIZE ,
  58 is created if
  59 .I key
  60 has the value
  61 .B IPC_PRIVATE
  62 or
  63 .I key
  64 isn't
  65 .BR IPC_PRIVATE ,
  66 no shared memory segment corresponding to
  67 .I key
  68 exists, and
  69 .B IPC_CREAT
  70 is specified in
  71 .IR shmflg .
  72 .PP
  73 If
  74 .I shmflg
  75 specifies both
  76 .B IPC_CREAT
  77 and
  78 .B IPC_EXCL
  79 and a shared memory segment already exists for
  80 .IR key ,
  81 then
  82 .BR shmget ()
  83 fails with
  84 .I errno
  85 set to
  86 .BR EEXIST .
  87 (This is analogous to the effect of the combination
  88 .B O_CREAT | O_EXCL
  89 for
  90 .BR open (2).)
  91 .PP
  92 The value
  93 .I shmflg
  94 is composed of:
  95 .TP 12
  96 .B IPC_CREAT
  97 Create a new segment.
  98 If this flag is not used, then
  99 .BR shmget ()
 100 will find the segment associated with \fIkey\fP and check to see if
 101 the user has permission to access the segment.
 102 .TP
 103 .B IPC_EXCL
 104 This flag is used with
 105 .B IPC_CREAT
 106 to ensure that this call creates the segment.
 107 If the segment already exists, the call fails.
 108 .TP
 109 .BR SHM_HUGETLB " (since Linux 2.6)"
 110 Allocate the segment using "huge pages."
 111 See the Linux kernel source file
 112 .I Documentation/vm/hugetlbpage.txt
 113 for further information.
 114 .TP
 115 .BR SHM_NORESERVE " (since Linux 2.6.15)"
 116 This flag serves the same purpose as the
 117 .BR mmap (2)
 118 .B MAP_NORESERVE
 119 flag.
 120 Do not reserve swap space for this segment.
 121 When swap space is reserved, one has the guarantee
 122 that it is possible to modify the segment.
 123 When swap space is not reserved one might get
 124 .B SIGSEGV
 125 upon a write
 126 if no physical memory is available.
 127 See also the discussion of the file
 128 .I /proc/sys/vm/overcommit_memory
 129 in
 130 .BR proc (5).
 131 .\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also
 132 .\" specified.
 133 .PP
 134 In addition to the above flags, the least significant 9 bits of
 135 .I shmflg
 136 specify the permissions granted to the owner, group, and others.
 137 These bits have the same format, and the same
 138 meaning, as the
 139 .I mode
 140 argument of
 141 .BR open (2).
 142 Presently, execute permissions are not used by the system.
 143 .PP
 144 When a new shared memory segment is created,
 145 its contents are initialized to zero values, and
 146 its associated data structure,
 147 .I shmid_ds
 148 (see
 149 .BR shmctl (2)),
 150 is initialized as follows:
 151 .IP
 152 .I shm_perm.cuid
 153 and
 154 .I shm_perm.uid
 155 are set to the effective user ID of the calling process.
 156 .IP
 157 .I shm_perm.cgid
 158 and
 159 .I shm_perm.gid
 160 are set to the effective group ID of the calling process.
 161 .IP
 162 The least significant 9 bits of
 163 .I shm_perm.mode
 164 are set to the least significant 9 bit of
 165 .IR shmflg .
 166 .IP
 167 .I shm_segsz
 168 is set to the value of
 169 .IR size .
 170 .IP
 171 .IR shm_lpid ,
 172 .IR shm_nattch ,
 173 .IR shm_atime ,
 174 and
 175 .I shm_dtime
 176 are set to 0.
 177 .IP
 178 .I shm_ctime
 179 is set to the current time.
 180 .PP
 181 If the shared memory segment already exists, the permissions are
 182 verified, and a check is made to see if it is marked for destruction.
 183 .SH RETURN VALUE
 184 On success, a valid shared memory identifier is returned.
 185 On error, \-1 is returned, and
 186 .I errno
 187 is set to indicate the error.
 188 .SH ERRORS
 189 On failure,
 190 .I errno
 191 is set to one of the following:
 192 .TP
 193 .B EACCES
 194 The user does not have permission to access the
 195 shared memory segment, and does not have the
 196 .B CAP_IPC_OWNER
 197 capability.
 198 .TP
 199 .B EEXIST
 200 .BR IPC_CREAT
 201 and
 202 .BR IPC_EXCL
 203 were specified in
 204 .IR shmflg ,
 205 but a shared memory segment already exists for
 206 .IR key .
 207 .TP
 208 .B EINVAL
 209 A new segment was to be created and
 210 .I size
 211 is less than
 212 .B SHMIN
 213 or greater than
 214 .BR SHMMAX .
 215 .TP
 216 .B EINVAL
 217 A segment for the given
 218 .I key
 219 exists, but \fIsize\fP is greater than the size
 220 of that segment.
 221 .TP
 222 .B ENFILE
 223 .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
 224 The system limit on the total number of open files has been reached.
 225 .TP
 226 .B ENOENT
 227 No segment exists for the given \fIkey\fP, and
 228 .B IPC_CREAT
 229 was not specified.
 230 .TP
 231 .B ENOMEM
 232 No memory could be allocated for segment overhead.
 233 .TP
 234 .B ENOSPC
 235 All possible shared memory IDs have been taken
 236 .RB ( SHMMNI ),
 237 or allocating a segment of the requested
 238 .I size
 239 would cause the system to exceed the system-wide limit on shared memory
 240 .RB ( SHMALL ).
 241 .TP
 242 .B EPERM
 243 The
 244 .B SHM_HUGETLB
 245 flag was specified, but the caller was not privileged (did not have the
 246 .B CAP_IPC_LOCK
 247 capability).
 248 .SH CONFORMING TO
 249 SVr4, POSIX.1-2001.
 250 .\" SVr4 documents an additional error condition EEXIST.
 251
 252 .B SHM_HUGETLB
 253 and
 254 .B SHM_NORESERVE
 255 are Linux extensions.
 256 .SH NOTES
 257 The inclusion of
 258 .I <sys/types.h>
 259 and
 260 .I <sys/ipc.h>
 261 isn't required on Linux or by any version of POSIX.
 262 However,
 263 some old implementations required the inclusion of these header files,
 264 and the SVID also documented their inclusion.
 265 Applications intended to be portable to such old systems may need
 266 to include these header files.
 267 .\" Like Linux, the FreeBSD man pages still document
 268 .\" the inclusion of these header files.
 269
 270 .B IPC_PRIVATE
 271 isn't a flag field but a
 272 .I key_t
 273 type.
 274 If this special value is used for
 275 .IR key ,
 276 the system call ignores all but the least significant 9 bits of
 277 .I shmflg
 278 and creates a new shared memory segment.
 279 .\"
 280 .SS Shared memory limits
 281 The following limits on shared memory segment resources affect the
 282 .BR shmget ()
 283 call:
 284 .TP
 285 .B SHMALL
 286 System-wide limit on the number of shared memory pages.
 287 Since Linux 2.4, the default value for this limit is
 288
 289     SHMMAX / PAGE_SIZE * (SHMMNI / 16)
 290
 291 If
 292 .B SHMMAX
 293 and
 294 .B SHMMNI
 295 are not modified, this yields a limit for the
 296 total memory used by all shared memory segments of 8 GB:
 297 With a 4kB page size, this formula yields the value 2^21 (2,097,152),
 298 with 8kB page size, it yields 2^20 (1048576).
 299
 300 On Linux, this limit can be read and modified via
 301 .IR /proc/sys/kernel/shmall .
 302 .TP
 303 .B SHMMAX
 304 Maximum size in bytes for a shared memory segment.
 305 Since Linux 2.2, the default value of this limit is 0x2000000 (32MB).
 306
 307 On Linux, this limit can be read and modified via
 308 .IR /proc/sys/kernel/shmmax .
 309 .TP
 310 .B SHMMIN
 311 Minimum size in bytes for a shared memory segment: implementation
 312 dependent (currently 1 byte, though
 313 .B PAGE_SIZE
 314 is the effective minimum size).
 315 .TP
 316 .B SHMMNI
 317 System-wide limit on the number of shared memory segments.
 318 In Linux 2.2, the default value for this limit was 128;
 319 since Linux 2.4, the default value is 4096.
 320
 321 On Linux, this limit can be read and modified via
 322 .IR /proc/sys/kernel/shmmni .
 323 .\" Kernels between 2.4.x and 2.6.8 had an off-by-one error that meant
 324 .\" that we could create one more segment than SHMMNI -- MTK
 325 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 326 .PP
 327 The implementation has no specific limits for the per-process maximum
 328 number of shared memory segments
 329 .RB ( SHMSEG ).
 330 .SS Linux notes
 331 Until version 2.3.30, Linux would return
 332 .B EIDRM
 333 for a
 334 .BR shmget ()
 335 on a shared memory segment scheduled for deletion.
 336 .SH BUGS
 337 The name choice
 338 .B IPC_PRIVATE
 339 was perhaps unfortunate,
 340 .B IPC_NEW
 341 would more clearly show its function.
 342 .SH SEE ALSO
 343 .BR shmat (2),
 344 .BR shmctl (2),
 345 .BR shmdt (2),
 346 .BR ftok (3),
 347 .BR capabilities (7),
 348 .BR shm_overview (7),
 349 .BR svipc (7)
 350 .SH COLOPHON
 351 This page is part of release 3.68 of the Linux
 352 .I man-pages
 353 project.
 354 A description of the project,
 355 information about reporting bugs,
 356 and the latest version of this page,
 357 can be found at
 358 \%http://www.kernel.org/doc/man\-pages/.