original/man2/semget.2

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   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 Tue Oct 22 17:54:56 1996 by Eric S. Raymond <esr@thyrsus.com>
  26 .\" Modified 1 Jan 2002, Martin Schulze <joey@infodrom.org>
  27 .\" Modified 4 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com>
  28 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  29 .\"     Added notes on capability requirements
  30 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  31 .\"     Language and formatting clean-ups
  32 .\"     Added notes on /proc files
  33 .\"     Rewrote BUGS note about semget()'s failure to initialize
  34 .\"             semaphore values
  35 .\"
  36 .TH SEMGET 2 2012-05-31 "Linux" "Linux Programmer's Manual"
  37 .SH NAME
  38 semget \- get a System V semaphore set identifier
  39 .SH SYNOPSIS
  40 .nf
  41 .B #include <sys/types.h>
  42 .B #include <sys/ipc.h>
  43 .B #include <sys/sem.h>
  44 .fi
  45 .sp
  46 .BI "int semget(key_t " key ,
  47 .BI "int " nsems ,
  48 .BI "int " semflg );
  49 .SH DESCRIPTION
  50 The
  51 .BR semget ()
  52 system call returns the System V semaphore set identifier
  53 associated with the argument
  54 .IR key .
  55 A new set of
  56 .I nsems
  57 semaphores is created if
  58 .I key
  59 has the value
  60 .B IPC_PRIVATE
  61 or if no existing semaphore set is associated with
  62 .I key
  63 and
  64 .B IPC_CREAT
  65 is specified in
  66 .IR semflg .
  67 .PP
  68 If
  69 .I semflg
  70 specifies both
  71 .B IPC_CREAT
  72 and
  73 .B IPC_EXCL
  74 and a semaphore set already exists for
  75 .IR key ,
  76 then
  77 .BR semget ()
  78 fails with
  79 .I errno
  80 set to
  81 .BR EEXIST .
  82 (This is analogous to the effect of the combination
  83 .B O_CREAT | O_EXCL
  84 for
  85 .BR open (2).)
  86 .PP
  87 Upon creation, the least significant 9 bits of the argument
  88 .I semflg
  89 define the permissions (for owner, group and others)
  90 for the semaphore set.
  91 These bits have the same format, and the same
  92 meaning, as the
  93 .I mode
  94 argument of
  95 .BR open (2)
  96 (though the execute permissions are
  97 not meaningful for semaphores, and write permissions mean permission
  98 to alter semaphore values).
  99 .PP
 100 The values of the semaphores in a newly created set are indeterminate.
 101 (POSIX.1-2001 is explicit on this point.)
 102 Although Linux, like many other implementations,
 103 initializes the semaphore values to 0,
 104 a portable application cannot rely on this:
 105 it should explicitly initialize the semaphores to the desired values.
 106 .\" In truth, every one of the many implementations that I've tested sets
 107 .\" the values to zero, but I suppose there is/was some obscure
 108 .\" implementation out there that does not.
 109 .PP
 110 When creating a new semaphore set,
 111 .BR semget ()
 112 initializes the set's associated data structure,
 113 .I semid_ds
 114 (see
 115 .BR semctl (2)),
 116 as follows:
 117 .IP
 118 .I sem_perm.cuid
 119 and
 120 .I sem_perm.uid
 121 are set to the effective user ID of the calling process.
 122 .IP
 123 .I sem_perm.cgid
 124 and
 125 .I sem_perm.gid
 126 are set to the effective group ID of the calling process.
 127 .IP
 128 The least significant 9 bits of
 129 .I sem_perm.mode
 130 are set to the least significant 9 bits of
 131 .IR semflg .
 132 .IP
 133 .I sem_nsems
 134 is set to the value of
 135 .IR nsems .
 136 .IP
 137 .I sem_otime
 138 is set to 0.
 139 .IP
 140 .I sem_ctime
 141 is set to the current time.
 142 .PP
 143 The argument
 144 .I nsems
 145 can be 0
 146 (a don't care)
 147 when a semaphore set is not being created.
 148 Otherwise
 149 .I nsems
 150 must be greater than 0
 151 and less than or equal to the maximum number of semaphores per semaphore set
 152 .RB ( SEMMSL ).
 153 .PP
 154 If the semaphore set already exists, the permissions are
 155 verified.
 156 .\" and a check is made to see if it is marked for destruction.
 157 .SH RETURN VALUE
 158 If successful, the return value will be the semaphore set identifier
 159 (a nonnegative integer), otherwise \-1
 160 is returned, with
 161 .I errno
 162 indicating the error.
 163 .SH ERRORS
 164 On failure
 165 .I errno
 166 will be set to one of the following:
 167 .TP
 168 .B EACCES
 169 A semaphore set exists for
 170 .IR key ,
 171 but the calling process does not have permission to access the set,
 172 and does not have the
 173 .B CAP_IPC_OWNER
 174 capability.
 175 .TP
 176 .B EEXIST
 177 A semaphore set exists for
 178 .I key
 179 and
 180 .I semflg
 181 specified both
 182 .B IPC_CREAT
 183 and
 184 .BR IPC_EXCL .
 185 .\" .TP
 186 .\" .B EIDRM
 187 .\" The semaphore set is marked to be deleted.
 188 .TP
 189 .B EINVAL
 190 .I nsems
 191 is less than 0 or greater than the limit on the number
 192 of semaphores per semaphore set
 193 .RB ( SEMMSL ),
 194 or a semaphore set corresponding to
 195 .I key
 196 already exists, and
 197 .I nsems
 198 is larger than the number of semaphores in that set.
 199 .TP
 200 .B ENOENT
 201 No semaphore set exists for
 202 .I key
 203 and
 204 .I semflg
 205 did not specify
 206 .BR IPC_CREAT .
 207 .TP
 208 .B ENOMEM
 209 A semaphore set has to be created but the system does not have
 210 enough memory for the new data structure.
 211 .TP
 212 .B ENOSPC
 213 A semaphore set has to be created but the system limit for the maximum
 214 number of semaphore sets
 215 .RB ( SEMMNI ),
 216 or the system wide maximum number of semaphores
 217 .RB ( SEMMNS ),
 218 would be exceeded.
 219 .SH CONFORMING TO
 220 SVr4, POSIX.1-2001.
 221 .\" SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN,
 222 .\" ERANGE, EFAULT.
 223 .SH NOTES
 224 The inclusion of
 225 .I <sys/types.h>
 226 and
 227 .I <sys/ipc.h>
 228 isn't required on Linux or by any version of POSIX.
 229 However,
 230 some old implementations required the inclusion of these header files,
 231 and the SVID also documented their inclusion.
 232 Applications intended to be portable to such old systems may need
 233 to include these header files.
 234 .\" Like Linux, the FreeBSD man pages still document
 235 .\" the inclusion of these header files.
 236
 237 .B IPC_PRIVATE
 238 isn't a flag field but a
 239 .I key_t
 240 type.
 241 If this special value is used for
 242 .IR key ,
 243 the system call ignores everything but the least significant 9 bits of
 244 .I semflg
 245 and creates a new semaphore set (on success).
 246 .PP
 247 The following limits on semaphore set resources affect the
 248 .BR semget ()
 249 call:
 250 .TP
 251 .B SEMMNI
 252 System wide maximum number of semaphore sets: policy dependent
 253 (on Linux, this limit can be read and modified via the fourth field of
 254 .IR /proc/sys/kernel/sem ).
 255 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 256 .TP
 257 .B SEMMSL
 258 Maximum number of semaphores per semid: implementation dependent
 259 (on Linux, this limit can be read and modified via the first field of
 260 .IR /proc/sys/kernel/sem ).
 261 .TP
 262 .B SEMMNS
 263 System wide maximum number of semaphores: policy dependent
 264 (on Linux, this limit can be read and modified via the second field of
 265 .IR /proc/sys/kernel/sem ).
 266 Values greater than
 267 .B SEMMSL * SEMMNI
 268 makes it irrelevant.
 269 .SH BUGS
 270 The name choice
 271 .B IPC_PRIVATE
 272 was perhaps unfortunate,
 273 .B IPC_NEW
 274 would more clearly show its function.
 275 .LP
 276 The semaphores in a set are not initialized by
 277 .BR semget ().
 278 .\" In fact they are initialized to zero on Linux, but POSIX.1-2001
 279 .\" does not specify this, and we can't portably rely on it.
 280 In order to initialize the semaphores,
 281 .BR semctl (2)
 282 must be used to perform a
 283 .B SETVAL
 284 or a
 285 .B SETALL
 286 operation on the semaphore set.
 287 (Where multiple peers do not know who will be the first to
 288 initialize the set, checking for a nonzero
 289 .I sem_otime
 290 in the associated data structure retrieved by a
 291 .BR semctl (2)
 292 .B IPC_STAT
 293 operation can be used to avoid races.)
 294 .SH SEE ALSO
 295 .BR semctl (2),
 296 .BR semop (2),
 297 .BR ftok (3),
 298 .BR capabilities (7),
 299 .BR sem_overview (7),
 300 .BR svipc (7)
 301 .SH COLOPHON
 302 This page is part of release 3.64 of the Linux
 303 .I man-pages
 304 project.
 305 A description of the project,
 306 and information about reporting bugs,
 307 can be found at
 308 \%http://www.kernel.org/doc/man\-pages/.