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 <mtk16@ext.canterbury.ac.nz>
  26 .\"
  27 .TH SEMGET 2 2002-01-04 "Linux 2.5" "Linux Programmer's Manual"
  28 .SH NAME
  29 semget \- get a semaphore set identifier
  30 .SH SYNOPSIS
  31 .nf
  32 .B
  33 #include <sys/types.h>
  34 .B
  35 #include <sys/ipc.h>
  36 .B
  37 #include <sys/sem.h>
  38 .fi
  39 .sp
  40 .BI "int semget(key_t " key ,
  41 .BI "int " nsems ,
  42 .BI "int " semflg );
  43 .SH DESCRIPTION
  44 This function returns the semaphore set identifier
  45 associated with the argument
  46 .IR key .
  47 A new set of
  48 .I nsems
  49 semaphores is created if
  50 .I key
  51 has the value
  52 .B IPC_PRIVATE
  53 or if no existing semaphore set is associated to
  54 .I key
  55 and
  56 .B IPC_CREAT
  57 is asserted in
  58 .I semflg
  59 (i.e.
  60 .IR semflg " &"
  61 .B IPC_CREAT
  62 isn't zero).
  63 .PP
  64 The presence in
  65 .I semflg
  66 of the fields
  67 .B IPC_CREAT
  68 and
  69 .B IPC_EXCL
  70 plays the same role, with respect to the existence
  71 of the semaphore set, as the presence
  72 of
  73 .B O_CREAT
  74 and
  75 .B O_EXCL
  76 in the mode argument of the
  77 .BR open (2)
  78 system call: i.e. the
  79 .B semget
  80 function fails if
  81 .I semflg
  82 asserts both
  83 .B IPC_CREAT
  84 and
  85 .B IPC_EXCL
  86 and a semaphore set already exists for
  87 .IR key .
  88 .PP
  89 Upon creation, the low-order 9 bits of the argument
  90 .I semflg
  91 define the access permissions (for owner, group and others)
  92 for the semaphore set.
  93 These bits have the same format, and the same
  94 meaning, as the mode argument in the
  95 .BR open (2)
  96 or
  97 .BR creat (2)
  98 system calls (though the execute permissions are
  99 not meaningful for semaphores, and write permissions mean permission
 100 to alter semaphore values).
 101 .PP
 102 When creating a new semaphore set,
 103 .B semget
 104 initializes the semaphore set's associated data structure
 105 .B semid_ds
 106 as follows:
 107 .IP
 108 .B sem_perm.cuid
 109 and
 110 .B sem_perm.uid
 111 are set to the effective user\-ID of the calling process.
 112 .IP
 113 .B sem_perm.cgid
 114 and
 115 .B sem_perm.gid
 116 are set to the effective group\-ID of the calling process.
 117 .IP
 118 The low-order 9 bits of
 119 .B sem_perm.mode
 120 are set to the low-order 9 bits of
 121 .IR semflg .
 122 .IP
 123 .B sem_nsems
 124 is set to the value of
 125 .IR nsems .
 126 .IP
 127 .B sem_otime
 128 is set to 0.
 129 .IP
 130 .B sem_ctime
 131 is set to the current time.
 132 .PP
 133 The argument
 134 .I nsems
 135 can be
 136 .B 0
 137 (a don't care)
 138 when a semaphore set is not being created.
 139 Otherwise
 140 .I nsems
 141 must be greater than
 142 .B 0
 143 and less than or equal to the maximum number of semaphores per semaphore set
 144 .RB ( SEMMSL ).
 145 .PP
 146 If the semaphore set already exists, the access permissions are
 147 verified.
 148 .\" and a check is made to see if it is marked for destruction.
 149 .SH "RETURN VALUE"
 150 If successful, the return value will be the semaphore set identifier
 151 (a nonnegative integer), otherwise
 152 .B \-1
 153 is returned, with
 154 .I errno
 155 indicating the error.
 156 .SH ERRORS
 157 On failure
 158 .I errno
 159 will be set to one of the following:
 160 .TP 11
 161 .B EACCES
 162 A semaphore set exists for
 163 .IR key ,
 164 but the calling process does not have permission to access the set.
 165 .TP
 166 .B EEXIST
 167 A semaphore set exists for
 168 .B key
 169 and
 170 .I semflg
 171 was asserting both
 172 .B IPC_CREAT
 173 and
 174 .BR IPC_EXCL .
 175 .\" .TP
 176 .\" .B EIDRM
 177 .\" The semaphore set is marked to be deleted.
 178 .TP
 179 .B ENOENT
 180 No semaphore set exists for
 181 .I key
 182 and
 183 .I semflg
 184 wasn't asserting
 185 .BR IPC_CREAT .
 186 .TP
 187 .B EINVAL
 188 .IR 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 ENOMEM
 199 A semaphore set has to be created but the system has not enough memory for
 200 the new data structure.
 201 .TP
 202 .B ENOSPC
 203 A semaphore set has to be created but the system limit for the maximum
 204 number of semaphore sets
 205 .RB ( SEMMNI ),
 206 or the system wide maximum number of semaphores
 207 .RB ( SEMMNS ),
 208 would be exceeded.
 209 .SH NOTES
 210 .B IPC_PRIVATE
 211 isn't a flag field but a
 212 .B key_t
 213 type.
 214 If this special value is used for
 215 .IR key ,
 216 the system call ignores everything but the low-order 9 bits of
 217 .I semflg
 218 and creates a new semaphore set (on success).
 219 .PP
 220 The followings are limits on semaphore set resources affecting a
 221 .B semget
 222 call:
 223 .TP 11
 224 .B SEMMNI
 225 System wide maximum number of semaphore sets: policy dependent.
 226 .TP
 227 .B SEMMSL
 228 Maximum number of semaphores per semid: implementation dependent
 229 (500 currently).
 230 .TP
 231 .B SEMMNS
 232 System wide maximum number of semaphores: policy dependent.
 233 Values greater than
 234 .B SEMMSL * SEMMNI
 235 makes it irrelevant.
 236 .SH BUGS
 237 Use of
 238 .B IPC_PRIVATE
 239 doesn't inhibit to other processes the access to the allocated
 240 semaphore set.
 241 .PP
 242 As for the files, there is currently no intrinsic way for a process to ensure
 243 exclusive access to a semaphore set.
 244 Asserting both
 245 .B IPC_CREAT
 246 and
 247 .B IPC_EXCL
 248 in
 249 .I semflg
 250 only ensures (on success) that a new semaphore set will be created,
 251 it doesn't imply exclusive access to the semaphore set.
 252 .PP
 253 The data structure associated with each semaphore in the set
 254 isn't initialized by the system call.
 255 In order to initialize those data structures, one has to execute a
 256 subsequent call to
 257 .BR semctl (2)
 258 to perform a
 259 .B SETVAL
 260 or a
 261 .B SETALL
 262 command on the semaphore set.
 263 .SH "CONFORMING TO"
 264 SVr4, SVID.
 265 SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN,
 266 ERANGE, EFAULT.
 267 .SH "SEE ALSO"
 268 .BR ftok (3),
 269 .BR ipc (5),
 270 .BR semctl (2),
 271 .BR semop (2)