1semget(2)                     System Calls Manual                    semget(2)
2
3
4

NAME

6       semget - get a System V semaphore set identifier
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/sem.h>
13
14       int semget(key_t key, int nsems, int semflg);
15

DESCRIPTION

17       The  semget() system call returns the System V semaphore set identifier
18       associated with the argument key.  It may be used either to obtain  the
19       identifier  of  a previously created semaphore set (when semflg is zero
20       and key does not have the value IPC_PRIVATE), or to create a new set.
21
22       A new set of nsems semaphores is created if key has the value  IPC_PRI‐
23       VATE  or  if  no  existing  semaphore  set  is  associated with key and
24       IPC_CREAT is specified in semflg.
25
26       If semflg specifies both IPC_CREAT and IPC_EXCL and a semaphore set al‐
27       ready  exists  for  key,  then semget() fails with errno set to EEXIST.
28       (This is analogous to the effect of the combination  O_CREAT  |  O_EXCL
29       for open(2).)
30
31       Upon  creation, the least significant 9 bits of the argument semflg de‐
32       fine the permissions (for owner, group, and others) for  the  semaphore
33       set.   These  bits  have  the same format, and the same meaning, as the
34       mode argument of open(2) (though the execute permissions are not  mean‐
35       ingful  for  semaphores, and write permissions mean permission to alter
36       semaphore values).
37
38       When creating a new semaphore set, semget() initializes the set's asso‐
39       ciated data structure, semid_ds (see semctl(2)), as follows:
40
41sem_perm.cuid  and  sem_perm.uid are set to the effective user ID of
42          the calling process.
43
44sem_perm.cgid and sem_perm.gid are set to the effective group ID  of
45          the calling process.
46
47       •  The  least  significant 9 bits of sem_perm.mode are set to the least
48          significant 9 bits of semflg.
49
50sem_nsems is set to the value of nsems.
51
52sem_otime is set to 0.
53
54sem_ctime is set to the current time.
55
56       The argument nsems can be 0 (a don't care) when a semaphore set is  not
57       being  created.   Otherwise, nsems must be greater than 0 and less than
58       or equal  to  the  maximum  number  of  semaphores  per  semaphore  set
59       (SEMMSL).
60
61       If the semaphore set already exists, the permissions are verified.
62

RETURN VALUE

64       On  success,  semget() returns the semaphore set identifier (a nonnega‐
65       tive integer).  On failure, -1 is returned, and errno is set  to  indi‐
66       cate the error.
67

ERRORS

69       EACCES A semaphore set exists for key, but the calling process does not
70              have permission to  access  the  set,  and  does  not  have  the
71              CAP_IPC_OWNER  capability in the user namespace that governs its
72              IPC namespace.
73
74       EEXIST IPC_CREAT and IPC_EXCL were specified in semflg, but a semaphore
75              set already exists for key.
76
77       EINVAL nsems  is less than 0 or greater than the limit on the number of
78              semaphores per semaphore set (SEMMSL).
79
80       EINVAL A semaphore set corresponding to key already exists,  but  nsems
81              is larger than the number of semaphores in that set.
82
83       ENOENT No  semaphore  set  exists  for  key  and semflg did not specify
84              IPC_CREAT.
85
86       ENOMEM A semaphore set has to be created but the system does  not  have
87              enough memory for the new data structure.
88
89       ENOSPC A  semaphore  set has to be created but the system limit for the
90              maximum number of semaphore sets (SEMMNI), or  the  system  wide
91              maximum number of semaphores (SEMMNS), would be exceeded.
92

STANDARDS

94       POSIX.1-2008.
95

HISTORY

97       SVr4, POSIX.1-2001.
98

NOTES

100       IPC_PRIVATE isn't a flag field but a key_t type.  If this special value
101       is used for key, the system call ignores all but the least  significant
102       9 bits of semflg and creates a new semaphore set (on success).
103
104   Semaphore initialization
105       The  values of the semaphores in a newly created set are indeterminate.
106       (POSIX.1-2001 and POSIX.1-2008 are explicit  on  this  point,  although
107       POSIX.1-2008 notes that a future version of the standard may require an
108       implementation to initialize the semaphores  to  0.)   Although  Linux,
109       like many other implementations, initializes the semaphore values to 0,
110       a portable application cannot rely on this: it should  explicitly  ini‐
111       tialize the semaphores to the desired values.
112
113       Initialization  can be done using semctl(2) SETVAL or SETALL operation.
114       Where multiple peers do not know who will be the  first  to  initialize
115       the set, checking for a nonzero sem_otime in the associated data struc‐
116       ture retrieved by a semctl(2) IPC_STAT operation can be used  to  avoid
117       races.
118
119   Semaphore limits
120       The  following  limits  on  semaphore set resources affect the semget()
121       call:
122
123       SEMMNI System-wide limit on the number of semaphore sets.  Before Linux
124              3.19,  the  default  value  for this limit was 128.  Since Linux
125              3.19, the default value is 32,000.  On Linux, this limit can  be
126              read and modified via the fourth field of /proc/sys/kernel/sem.
127
128       SEMMSL Maximum  number  of  semaphores  per semaphore ID.  Before Linux
129              3.19, the default value for this limit  was  250.   Since  Linux
130              3.19,  the default value is 32,000.  On Linux, this limit can be
131              read and modified via the first field of /proc/sys/kernel/sem.
132
133       SEMMNS System-wide limit on the number of semaphores: policy  dependent
134              (on  Linux,  this  limit can be read and modified via the second
135              field of /proc/sys/kernel/sem).  Note that the number  of  sema‐
136              phores  system-wide is also limited by the product of SEMMSL and
137              SEMMNI.
138

BUGS

140       The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW would more
141       clearly show its function.
142

EXAMPLES

144       The  program shown below uses semget() to create a new semaphore set or
145       retrieve the ID of an existing set.  It generates the key for  semget()
146       using  ftok(3).   The  first two command-line arguments are used as the
147       pathname and proj_id arguments for ftok(3).  The third command-line ar‐
148       gument  is  an  integer that specifies the nsems argument for semget().
149       Command-line options can be used to  specify  the  IPC_CREAT  (-c)  and
150       IPC_EXCL  (-x)  flags for the call to semget().  The usage of this pro‐
151       gram is demonstrated below.
152
153       We first create two files that will be  used  to  generate  keys  using
154       ftok(3), create two semaphore sets using those files, and then list the
155       sets using ipcs(1):
156
157           $ touch mykey mykey2
158           $ ./t_semget -c mykey p 1
159           ID = 9
160           $ ./t_semget -c mykey2 p 2
161           ID = 10
162           $ ipcs -s
163
164           ------ Semaphore Arrays --------
165           key        semid      owner      perms      nsems
166           0x7004136d 9          mtk        600        1
167           0x70041368 10         mtk        600        2
168
169       Next, we demonstrate that when semctl(2) is given the same key (as gen‐
170       erated  by the same arguments to ftok(3)), it returns the ID of the al‐
171       ready existing semaphore set:
172
173           $ ./t_semget -c mykey p 1
174           ID = 9
175
176       Finally, we demonstrate the kind  of  collision  that  can  occur  when
177       ftok(3)  is given different pathname arguments that have the same inode
178       number:
179
180           $ ln mykey link
181           $ ls -i1 link mykey
182           2233197 link
183           2233197 mykey
184           $ ./t_semget link p 1       # Generates same key as 'mykey'
185           ID = 9
186
187   Program source
188
189       /* t_semget.c
190
191          Licensed under GNU General Public License v2 or later.
192       */
193       #include <stdio.h>
194       #include <stdlib.h>
195       #include <sys/ipc.h>
196       #include <sys/sem.h>
197       #include <unistd.h>
198
199       static void
200       usage(const char *pname)
201       {
202           fprintf(stderr, "Usage: %s [-cx] pathname proj-id num-sems\n",
203                   pname);
204           fprintf(stderr, "    -c           Use IPC_CREAT flag\n");
205           fprintf(stderr, "    -x           Use IPC_EXCL flag\n");
206           exit(EXIT_FAILURE);
207       }
208
209       int
210       main(int argc, char *argv[])
211       {
212           int    semid, nsems, flags, opt;
213           key_t  key;
214
215           flags = 0;
216           while ((opt = getopt(argc, argv, "cx")) != -1) {
217               switch (opt) {
218               case 'c': flags |= IPC_CREAT;   break;
219               case 'x': flags |= IPC_EXCL;    break;
220               default:  usage(argv[0]);
221               }
222           }
223
224           if (argc != optind + 3)
225               usage(argv[0]);
226
227           key = ftok(argv[optind], argv[optind + 1][0]);
228           if (key == -1) {
229               perror("ftok");
230               exit(EXIT_FAILURE);
231           }
232
233           nsems = atoi(argv[optind + 2]);
234
235           semid = semget(key, nsems, flags | 0600);
236           if (semid == -1) {
237               perror("semget");
238               exit(EXIT_FAILURE);
239           }
240
241           printf("ID = %d\n", semid);
242
243           exit(EXIT_SUCCESS);
244       }
245

SEE ALSO

247       semctl(2),   semop(2),   ftok(3),   capabilities(7),   sem_overview(7),
248       sysvipc(7)
249
250
251
252Linux man-pages 6.05              2023-05-03                         semget(2)
Impressum