original/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 .br
  43 .B #include <sys/shm.h>
  44 .sp
  45 .BI "int shmget(key_t " key ", size_t " size ", int " shmflg );
  46 .ad b
  47 .SH DESCRIPTION
  48 .BR shmget ()
  49 returns the identifier of the shared memory segment
  50 associated with the value of the argument
  51 .IR key .
  52 A new shared memory segment, with size equal to the value of
  53 .I size
  54 rounded up to a multiple of
  55 .BR PAGE_SIZE ,
  56 is created if
  57 .I key
  58 has the value
  59 .B IPC_PRIVATE
  60 or
  61 .I key
  62 isn't
  63 .BR IPC_PRIVATE ,
  64 no shared memory segment corresponding to
  65 .I key
  66 exists, and
  67 .B IPC_CREAT
  68 is specified in
  69 .IR shmflg .
  70 .PP
  71 If
  72 .I shmflg
  73 specifies both
  74 .B IPC_CREAT
  75 and
  76 .B IPC_EXCL
  77 and a shared memory segment already exists for
  78 .IR key ,
  79 then
  80 .BR shmget ()
  81 fails with
  82 .I errno
  83 set to
  84 .BR EEXIST .
  85 (This is analogous to the effect of the combination
  86 .B O_CREAT | O_EXCL
  87 for
  88 .BR open (2).)
  89 .PP
  90 The value
  91 .I shmflg
  92 is composed of:
  93 .TP 12
  94 .B IPC_CREAT
  95 to create a new segment.
  96 If this flag is not used, then
  97 .BR shmget ()
  98 will find the segment associated with \fIkey\fP and check to see if
  99 the user has permission to access the segment.
 100 .TP
 101 .B IPC_EXCL
 102 used with \fBIPC_CREAT\fP to ensure failure if the segment already exists.
 103 .TP
 104 .I mode_flags
 105 (least significant 9 bits)
 106 specifying the permissions granted to the owner, group, and world.
 107 These bits have the same format, and the same
 108 meaning, as the
 109 .I mode
 110 argument of
 111 .BR open (2).
 112 Presently, the execute permissions are not used by the system.
 113 .TP
 114 .BR SHM_HUGETLB " (since Linux 2.6)"
 115 Allocate the segment using "huge pages."
 116 See the kernel source file
 117 .I Documentation/vm/hugetlbpage.txt
 118 for further information.
 119 .TP
 120 .BR SHM_NORESERVE " (since Linux 2.6.15)"
 121 This flag serves the same purpose as the
 122 .BR mmap (2)
 123 .B MAP_NORESERVE
 124 flag.
 125 Do not reserve swap space for this segment.
 126 When swap space is reserved, one has the guarantee
 127 that it is possible to modify the segment.
 128 When swap space is not reserved one might get
 129 .B SIGSEGV
 130 upon a write
 131 if no physical memory is available.
 132 See also the discussion of the file
 133 .I /proc/sys/vm/overcommit_memory
 134 in
 135 .BR proc (5).
 136 .\" As at 2.6.17-rc2, this flag has no effect if SHM_HUGETLB was also
 137 .\" specified.
 138 .PP
 139 When a new shared memory segment is created,
 140 its contents are initialized to zero values, and
 141 its associated data structure,
 142 .I shmid_ds
 143 (see
 144 .BR shmctl (2)),
 145 is initialized as follows:
 146 .IP
 147 .I shm_perm.cuid
 148 and
 149 .I shm_perm.uid
 150 are set to the effective user ID of the calling process.
 151 .IP
 152 .I shm_perm.cgid
 153 and
 154 .I shm_perm.gid
 155 are set to the effective group ID of the calling process.
 156 .IP
 157 The least significant 9 bits of
 158 .I shm_perm.mode
 159 are set to the least significant 9 bit of
 160 .IR shmflg .
 161 .IP
 162 .I shm_segsz
 163 is set to the value of
 164 .IR size .
 165 .IP
 166 .IR shm_lpid ,
 167 .IR shm_nattch ,
 168 .I shm_atime
 169 and
 170 .I shm_dtime
 171 are set to 0.
 172 .IP
 173 .I shm_ctime
 174 is set to the current time.
 175 .PP
 176 If the shared memory segment already exists, the permissions are
 177 verified, and a check is made to see if it is marked for destruction.
 178 .SH "RETURN VALUE"
 179 A valid segment identifier,
 180 .IR shmid ,
 181 is returned on success, \-1 on error.
 182 .SH ERRORS
 183 On failure,
 184 .I errno
 185 is set to one of the following:
 186 .TP
 187 .B EACCES
 188 The user does not have permission to access the
 189 shared memory segment, and does not have the
 190 .B CAP_IPC_OWNER
 191 capability.
 192 .TP
 193 .B EEXIST
 194 .B IPC_CREAT | IPC_EXCL
 195 was specified and the segment exists.
 196 .TP
 197 .B EINVAL
 198 A new segment was to be created and \fIsize\fP < \fBSHMMIN\fP
 199 or \fIsize\fP > \fBSHMMAX\fP, or no new segment was to be created,
 200 a segment with given key existed, but \fIsize\fP is greater than the size
 201 of that segment.
 202 .TP
 203 .B ENFILE
 204 .\" [2.6.7] shmem_zero_setup()-->shmem_file_setup()-->get_empty_filp()
 205 The system limit on the total number of open files has been reached.
 206 .TP
 207 .B ENOENT
 208 No segment exists for the given \fIkey\fP, and
 209 .B IPC_CREAT
 210 was not specified.
 211 .TP
 212 .B ENOMEM
 213 No memory could be allocated for segment overhead.
 214 .TP
 215 .B ENOSPC
 216 All possible shared memory IDs have been taken
 217 .RB ( SHMMNI ),
 218 or allocating a segment of the requested
 219 .I size
 220 would cause the system to exceed the system-wide limit on shared memory
 221 .RB ( SHMALL ).
 222 .TP
 223 .B EPERM
 224 The
 225 .B SHM_HUGETLB
 226 flag was specified, but the caller was not privileged (did not have the
 227 .B CAP_IPC_LOCK
 228 capability).
 229 .SH "CONFORMING TO"
 230 SVr4, POSIX.1-2001.
 231 .\" SVr4 documents an additional error condition EEXIST.
 232
 233 .B SHM_HUGETLB
 234 is a nonportable Linux extension.
 235 .SH NOTES
 236 .B IPC_PRIVATE
 237 isn't a flag field but a
 238 .I key_t
 239 type.
 240 If this special value is used for
 241 .IR key ,
 242 the system call ignores everything but the least significant 9 bits of
 243 .I shmflg
 244 and creates a new shared memory segment (on success).
 245 .PP
 246 The following limits on shared memory segment resources affect the
 247 .BR shmget ()
 248 call:
 249 .TP
 250 .B SHMALL
 251 System wide maximum of shared memory pages
 252 (on Linux, this limit can be read and modified via
 253 .IR /proc/sys/kernel/shmall ).
 254 .TP
 255 .B SHMMAX
 256 Maximum size in bytes for a shared memory segment: policy dependent
 257 (on Linux, this limit can be read and modified via
 258 .IR /proc/sys/kernel/shmmax ).
 259 .TP
 260 .B SHMMIN
 261 Minimum size in bytes for a shared memory segment: implementation
 262 dependent (currently 1 byte, though
 263 .B PAGE_SIZE
 264 is the effective minimum size).
 265 .TP
 266 .B SHMMNI
 267 System wide maximum number of shared memory segments: implementation
 268 dependent (currently 4096, was 128 before Linux 2.3.99;
 269 on Linux, this limit can be read and modified via
 270 .IR /proc/sys/kernel/shmmni ).
 271 .\" Kernels between 2.4.x and 2.6.8 had an off-by-one error that meant
 272 .\" that we could create one more segment than SHMMNI -- MTK
 273 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 274 .PP
 275 The implementation has no specific limits for the per-process maximum
 276 number of shared memory segments
 277 .RB ( SHMSEG ).
 278 .SS Linux Notes
 279 Until version 2.3.30 Linux would return
 280 .B EIDRM
 281 for a
 282 .BR shmget ()
 283 on a shared memory segment scheduled for deletion.
 284 .SH BUGS
 285 The name choice
 286 .B IPC_PRIVATE
 287 was perhaps unfortunate,
 288 .B IPC_NEW
 289 would more clearly show its function.
 290 .SH "SEE ALSO"
 291 .BR shmat (2),
 292 .BR shmctl (2),
 293 .BR shmdt (2),
 294 .BR ftok (3),
 295 .BR capabilities (7),
 296 .BR shm_overview (7),
 297 .BR svipc (7)