original/man2/semget.2

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