man2/shmget.2

   1 .\" Copyright (c) 1993 Luigi P. Bai (lpb@softint.com) July 28, 1993
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Modified Wed Jul 28 10:57:35 1993, Rik Faith <faith@cs.unc.edu>
  24 .\" Modified Sun Nov 28 16:43:30 1993, Rik Faith <faith@cs.unc.edu>
  25 .\"          with material from Giorgio Ciucci <giorgio@crcc.it>
  26 .\" Portions Copyright 1993 Giorgio Ciucci <giorgio@crcc.it>
  27 .\" Modified Tue Oct 22 22:03:17 1996 by Eric S. Raymond <esr@thyrsus.com>
  28 .\" Modified, 8 Jan 2003, Michael Kerrisk, <mtk.manpages@gmail.com>
  29 .\"     Removed EIDRM from errors - that can't happen...
  30 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  31 .\"     Added notes on capability requirements
  32 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  33 .\"     Language and formatting clean-ups
  34 .\"     Added notes on /proc files
  35 .\"
  36 .TH SHMGET 2 2006-05-02 "Linux" "Linux Programmer's Manual"
  37 .SH NAME
  38 shmget \- allocates a shared memory segment
  39 .SH SYNOPSIS
  40 .ad l
  41 .B #include <sys/ipc.h>
  42 .B #include <sys/shm.h>
  43 .sp
  44 .BI "int shmget(key_t " key ", size_t " size ", int " shmflg );
  45 .ad b
  46 .SH DESCRIPTION
  47 .BR shmget ()
  48 returns the identifier of the shared memory segment
  49 associated with the value of the argument
  50 .IR key .
  51 A new shared memory segment, with size equal to the value of
  52 .I size
  53 rounded up to a multiple of
  54 .BR PAGE_SIZE ,
  55 is created if
  56 .I key
  57 has the value
  58 .B IPC_PRIVATE
  59 or
  60 .I key
  61 isn't
  62 .BR IPC_PRIVATE ,
  63 no shared memory segment corresponding to
  64 .I key
  65 exists, and
  66 .B IPC_CREAT
  67 is specified in
  68 .IR shmflg .
  69 .PP
  70 If
  71 .I shmflg
  72 specifies both
  73 .B IPC_CREAT
  74 and
  75 .B IPC_EXCL
  76 and a shared memory segment already exists for
  77 .IR key ,
  78 then
  79 .BR shmget ()
  80 fails with
  81 .I errno
  82 set to
  83 .BR EEXIST .
  84 (This is analogous to the effect of the combination
  85 .B O_CREAT | O_EXCL
  86 for
  87 .BR open (2).)
  88 .PP
  89 The value
  90 .I shmflg
  91 is composed of:
  92 .TP 12
  93 .B IPC_CREAT
  94 to create a new segment.
  95 If this flag is not used, then
  96 .BR shmget ()
  97 will find the segment associated with \fIkey\fP and check to see if
  98 the user has permission to access the segment.
  99 .TP
 100 .B IPC_EXCL
 101 used with \fBIPC_CREAT\fP to ensure failure if the segment already exists.
 102 .TP
 103 .I mode_flags
 104 (least significant 9 bits)
 105 specifying the permissions granted to the owner, group, and world.
 106 These bits have the same format, and the same
 107 meaning, as the
 108 .I mode
 109 argument of
 110 .BR open (2).
 111 Presently, the execute permissions are not used by the system.
 112 .TP
 113 .BR SHM_HUGETLB " (since Linux 2.6)"
 114 Allocate the segment using "huge pages."
 115 See the kernel source file
 116 .I Documentation/vm/hugetlbpage.txt
 117 for further information.
 118 .TP
 119 .BR SHM_NORESERVE " (since Linux 2.6.15)"
 120 This flag serves the same purpose as the
 121 .BR mmap (2)
 122 .B MAP_NORESERVE
 123 flag.
 124 Do not reserve swap space for this segment.
 125 When swap space is reserved, one has the guarantee
 126 that it is possible to modify the segment.
 127 When swap space is not reserved one might get
 128 .B SIGSEGV
 129 upon a write
 130 if no physical memory is available.
 131 See also the discussion of the file
 132 .I /proc/sys/vm/overcommit_memory
 133 in
 134 .BR proc (5).
 135 .\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also
 136 .\" specified.
 137 .PP
 138 When a new shared memory segment is created,
 139 its contents are initialized to zero values, and
 140 its associated data structure,
 141 .I shmid_ds
 142 (see
 143 .BR shmctl (2)),
 144 is initialized as follows:
 145 .IP
 146 .I shm_perm.cuid
 147 and
 148 .I shm_perm.uid
 149 are set to the effective user ID of the calling process.
 150 .IP
 151 .I shm_perm.cgid
 152 and
 153 .I shm_perm.gid
 154 are set to the effective group ID of the calling process.
 155 .IP
 156 The least significant 9 bits of
 157 .I shm_perm.mode
 158 are set to the least significant 9 bit of
 159 .IR shmflg .
 160 .IP
 161 .I shm_segsz
 162 is set to the value of
 163 .IR size .
 164 .IP
 165 .IR shm_lpid ,
 166 .IR shm_nattch ,
 167 .I shm_atime
 168 and
 169 .I shm_dtime
 170 are set to 0.
 171 .IP
 172 .I shm_ctime
 173 is set to the current time.
 174 .PP
 175 If the shared memory segment already exists, the permissions are
 176 verified, and a check is made to see if it is marked for destruction.
 177 .SH "RETURN VALUE"
 178 A valid segment identifier,
 179 .IR shmid ,
 180 is returned on success, \-1 on error.
 181 .SH ERRORS
 182 On failure,
 183 .I errno
 184 is set to one of the following:
 185 .TP 12
 186 .B EACCES
 187 The user does not have permission to access the
 188 shared memory segment, and does not have the
 189 .B CAP_IPC_OWNER
 190 capability.
 191 .TP
 192 .B EEXIST
 193 .B IPC_CREAT | IPC_EXCL
 194 was specified and the segment exists.
 195 .TP
 196 .B EINVAL
 197 A new segment was to be created and \fIsize\fP < \fBSHMMIN\fP
 198 or \fIsize\fP > \fBSHMMAX\fP, or no new segment was to be created,
 199 a segment with given key existed, but \fIsize\fP is greater than the size
 200 of that segment.
 201 .TP
 202 .B ENFILE
 203 .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
 204 The system limit on the total number of open files has been reached.
 205 .TP
 206 .B ENOENT
 207 No segment exists for the given \fIkey\fP, and
 208 .B IPC_CREAT
 209 was not specified.
 210 .TP
 211 .B ENOMEM
 212 No memory could be allocated for segment overhead.
 213 .TP
 214 .B ENOSPC
 215 All possible shared memory IDs have been taken
 216 .RB ( SHMMNI ),
 217 or allocating a segment of the requested
 218 .I size
 219 would cause the system to exceed the system-wide limit on shared memory
 220 .RB ( SHMALL ).
 221 .TP
 222 .B EPERM
 223 The
 224 .B SHM_HUGETLB
 225 flag was specified, but the caller was not privileged (did not have the
 226 .B CAP_IPC_LOCK
 227 capability).
 228 .SH "CONFORMING TO"
 229 SVr4, POSIX.1-2001.
 230 .\" SVr4 documents an additional error condition EEXIST.
 231
 232 .B SHM_HUGETLB
 233 is a non-portable Linux extension.
 234 .SH NOTES
 235 .B IPC_PRIVATE
 236 isn't a flag field but a
 237 .I key_t
 238 type.
 239 If this special value is used for
 240 .IR key ,
 241 the system call ignores everything but the least significant 9 bits of
 242 .I shmflg
 243 and creates a new shared memory segment (on success).
 244 .PP
 245 The following limits on shared memory segment resources affect the
 246 .BR shmget ()
 247 call:
 248 .TP 11
 249 .B SHMALL
 250 System wide maximum of shared memory pages
 251 (on Linux, this limit can be read and modified via
 252 .IR /proc/sys/kernel/shmall ).
 253 .TP
 254 .B SHMMAX
 255 Maximum size in bytes for a shared memory segment: policy dependent
 256 (on Linux, this limit can be read and modified via
 257 .IR /proc/sys/kernel/shmmax ).
 258 .TP
 259 .B SHMMIN
 260 Minimum size in bytes for a shared memory segment: implementation
 261 dependent (currently 1 byte, though
 262 .B PAGE_SIZE
 263 is the effective minimum size).
 264 .TP
 265 .B SHMMNI
 266 System wide maximum number of shared memory segments: implementation
 267 dependent (currently 4096, was 128 before Linux 2.3.99;
 268 on Linux, this limit can be read and modified via
 269 .IR /proc/sys/kernel/shmmni ).
 270 .\" Kernels between 2.4.x and 2.6.8 had an off-by-one error that meant
 271 .\" that we could create one more segment than SHMMNI -- MTK
 272 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 273 .PP
 274 The implementation has no specific limits for the per process maximum
 275 number of shared memory segments
 276 .RB ( SHMSEG ).
 277 .SS Linux Notes
 278 Until version 2.3.30 Linux would return
 279 .B EIDRM
 280 for a
 281 .BR shmget ()
 282 on a shared memory segment scheduled for deletion.
 283 .SH BUGS
 284 The name choice
 285 .B IPC_PRIVATE
 286 was perhaps unfortunate, IPC_NEW
 287 would more clearly show its function.
 288 .SH "SEE ALSO"
 289 .BR shmat (2),
 290 .BR shmctl (2),
 291 .BR shmdt (2),
 292 .BR ftok (3),
 293 .BR capabilities (7),
 294 .BR svipc (7)