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 2013-04-19 "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 to 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 used with \fBIPC_CREAT\fP to ensure failure if the segment already exists.
 105 .TP
 106 .I mode_flags
 107 (least significant 9 bits)
 108 specifying the permissions granted to the owner, group, and world.
 109 These bits have the same format, and the same
 110 meaning, as the
 111 .I mode
 112 argument of
 113 .BR open (2).
 114 Presently, the execute permissions are not used by the system.
 115 .TP
 116 .BR SHM_HUGETLB " (since Linux 2.6)"
 117 Allocate the segment using "huge pages."
 118 See the Linux kernel source file
 119 .I Documentation/vm/hugetlbpage.txt
 120 for further information.
 121 .TP
 122 .BR SHM_NORESERVE " (since Linux 2.6.15)"
 123 This flag serves the same purpose as the
 124 .BR mmap (2)
 125 .B MAP_NORESERVE
 126 flag.
 127 Do not reserve swap space for this segment.
 128 When swap space is reserved, one has the guarantee
 129 that it is possible to modify the segment.
 130 When swap space is not reserved one might get
 131 .B SIGSEGV
 132 upon a write
 133 if no physical memory is available.
 134 See also the discussion of the file
 135 .I /proc/sys/vm/overcommit_memory
 136 in
 137 .BR proc (5).
 138 .\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also
 139 .\" specified.
 140 .PP
 141 When a new shared memory segment is created,
 142 its contents are initialized to zero values, and
 143 its associated data structure,
 144 .I shmid_ds
 145 (see
 146 .BR shmctl (2)),
 147 is initialized as follows:
 148 .IP
 149 .I shm_perm.cuid
 150 and
 151 .I shm_perm.uid
 152 are set to the effective user ID of the calling process.
 153 .IP
 154 .I shm_perm.cgid
 155 and
 156 .I shm_perm.gid
 157 are set to the effective group ID of the calling process.
 158 .IP
 159 The least significant 9 bits of
 160 .I shm_perm.mode
 161 are set to the least significant 9 bit of
 162 .IR shmflg .
 163 .IP
 164 .I shm_segsz
 165 is set to the value of
 166 .IR size .
 167 .IP
 168 .IR shm_lpid ,
 169 .IR shm_nattch ,
 170 .IR shm_atime ,
 171 and
 172 .I shm_dtime
 173 are set to 0.
 174 .IP
 175 .I shm_ctime
 176 is set to the current time.
 177 .PP
 178 If the shared memory segment already exists, the permissions are
 179 verified, and a check is made to see if it is marked for destruction.
 180 .SH RETURN VALUE
 181 On success, a valid shared memory identifier is returned.
 182 On error, \-1 is returned, and
 183 .I errno
 184 is set to indicate the error.
 185 .SH ERRORS
 186 On failure,
 187 .I errno
 188 is set to one of the following:
 189 .TP
 190 .B EACCES
 191 The user does not have permission to access the
 192 shared memory segment, and does not have the
 193 .B CAP_IPC_OWNER
 194 capability.
 195 .TP
 196 .B EEXIST
 197 .B IPC_CREAT | IPC_EXCL
 198 was specified and the segment exists.
 199 .TP
 200 .B EINVAL
 201 A new segment was to be created and \fIsize\fP < \fBSHMMIN\fP
 202 or \fIsize\fP > \fBSHMMAX\fP, or no new segment was to be created,
 203 a segment with given key existed, but \fIsize\fP is greater than the size
 204 of that segment.
 205 .TP
 206 .B ENFILE
 207 .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
 208 The system limit on the total number of open files has been reached.
 209 .TP
 210 .B ENOENT
 211 No segment exists for the given \fIkey\fP, and
 212 .B IPC_CREAT
 213 was not specified.
 214 .TP
 215 .B ENOMEM
 216 No memory could be allocated for segment overhead.
 217 .TP
 218 .B ENOSPC
 219 All possible shared memory IDs have been taken
 220 .RB ( SHMMNI ),
 221 or allocating a segment of the requested
 222 .I size
 223 would cause the system to exceed the system-wide limit on shared memory
 224 .RB ( SHMALL ).
 225 .TP
 226 .B EPERM
 227 The
 228 .B SHM_HUGETLB
 229 flag was specified, but the caller was not privileged (did not have the
 230 .B CAP_IPC_LOCK
 231 capability).
 232 .SH CONFORMING TO
 233 SVr4, POSIX.1-2001.
 234 .\" SVr4 documents an additional error condition EEXIST.
 235
 236 .B SHM_HUGETLB
 237 is a nonportable Linux extension.
 238 .SH NOTES
 239 The inclusion of
 240 .I <sys/types.h>
 241 and
 242 .I <sys/ipc.h>
 243 isn't required on Linux or by any version of POSIX.
 244 However,
 245 some old implementations required the inclusion of these header files,
 246 and the SVID also documented their inclusion.
 247 Applications intended to be portable to such old systems may need
 248 to include these header files.
 249 .\" Like Linux, the FreeBSD man pages still document
 250 .\" the inclusion of these header files.
 251
 252 .B IPC_PRIVATE
 253 isn't a flag field but a
 254 .I key_t
 255 type.
 256 If this special value is used for
 257 .IR key ,
 258 the system call ignores everything but the least significant 9 bits of
 259 .I shmflg
 260 and creates a new shared memory segment (on success).
 261 .PP
 262 The following limits on shared memory segment resources affect the
 263 .BR shmget ()
 264 call:
 265 .TP
 266 .B SHMALL
 267 System wide maximum of shared memory pages
 268 (on Linux, this limit can be read and modified via
 269 .IR /proc/sys/kernel/shmall ).
 270 .TP
 271 .B SHMMAX
 272 Maximum size in bytes for a shared memory segment: policy dependent
 273 (on Linux, this limit can be read and modified via
 274 .IR /proc/sys/kernel/shmmax ).
 275 .TP
 276 .B SHMMIN
 277 Minimum size in bytes for a shared memory segment: implementation
 278 dependent (currently 1 byte, though
 279 .B PAGE_SIZE
 280 is the effective minimum size).
 281 .TP
 282 .B SHMMNI
 283 System wide maximum number of shared memory segments: implementation
 284 dependent (currently 4096, was 128 before Linux 2.3.99;
 285 on Linux, this limit can be read and modified via
 286 .IR /proc/sys/kernel/shmmni ).
 287 .\" Kernels between 2.4.x and 2.6.8 had an off-by-one error that meant
 288 .\" that we could create one more segment than SHMMNI -- MTK
 289 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 290 .PP
 291 The implementation has no specific limits for the per-process maximum
 292 number of shared memory segments
 293 .RB ( SHMSEG ).
 294 .SS Linux notes
 295 Until version 2.3.30 Linux would return
 296 .B EIDRM
 297 for a
 298 .BR shmget ()
 299 on a shared memory segment scheduled for deletion.
 300 .SH BUGS
 301 The name choice
 302 .B IPC_PRIVATE
 303 was perhaps unfortunate,
 304 .B IPC_NEW
 305 would more clearly show its function.
 306 .SH SEE ALSO
 307 .BR shmat (2),
 308 .BR shmctl (2),
 309 .BR shmdt (2),
 310 .BR ftok (3),
 311 .BR capabilities (7),
 312 .BR shm_overview (7),
 313 .BR svipc (7)