1semget(2) System Calls Manual semget(2)
2
6 semget - get a System V semaphore set identifier
7
9 Standard C library (libc, -lc)
10
12 #include <sys/sem.h>
13 int semget(key_t key, int nsems, int semflg);
15
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 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 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 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 When creating a new semaphore set, semget() initializes the set's asso‐
39 ciated data structure, semid_ds (see semctl(2)), as follows:
40 • sem_perm.cuid and sem_perm.uid are set to the effective user ID of
42 the calling process.
43 • sem_perm.cgid and sem_perm.gid are set to the effective group ID of
45 the calling process.
46 • The least significant 9 bits of sem_perm.mode are set to the least
48 significant 9 bits of semflg.
49 • sem_nsems is set to the value of nsems.
51 • sem_otime is set to 0.
53 • sem_ctime is set to the current time.
55 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 If the semaphore set already exists, the permissions are verified.
62
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
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 EEXIST IPC_CREAT and IPC_EXCL were specified in semflg, but a semaphore
75 set already exists for key.
76 EINVAL nsems is less than 0 or greater than the limit on the number of
78 semaphores per semaphore set (SEMMSL).
79 EINVAL A semaphore set corresponding to key already exists, but nsems
81 is larger than the number of semaphores in that set.
82 ENOENT No semaphore set exists for key and semflg did not specify
84 IPC_CREAT.
85 ENOMEM A semaphore set has to be created but the system does not have
87 enough memory for the new data structure.
88 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
94 POSIX.1-2008.
95
97 SVr4, POSIX.1-2001.
98
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 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 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 Semaphore limits
120 The following limits on semaphore set resources affect the semget()
121 call:
122 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 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 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
140 The name choice IPC_PRIVATE was perhaps unfortunate, IPC_NEW would more
141 clearly show its function.
142
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 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 $ 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 ------ Semaphore Arrays --------
165 key semid owner perms nsems
166 0x7004136d 9 mtk 600 1
167 0x70041368 10 mtk 600 2
168 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 $ ./t_semget -c mykey p 1
174 ID = 9
175 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 $ 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 Program source
188 /* t_semget.c
190 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 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 int
210 main(int argc, char *argv[])
211 {
212 int semid, nsems, flags, opt;
213 key_t key;
214 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 if (argc != optind + 3)
225 usage(argv[0]);
226 key = ftok(argv[optind], argv[optind + 1][0]);
228 if (key == -1) {
229 perror("ftok");
230 exit(EXIT_FAILURE);
231 }
232 nsems = atoi(argv[optind + 2]);
234 semid = semget(key, nsems, flags | 0600);
236 if (semid == -1) {
237 perror("semget");
238 exit(EXIT_FAILURE);
239 }
240 printf("ID = %d\n", semid);
242 exit(EXIT_SUCCESS);
244 }
245
247 semctl(2), semop(2), ftok(3), capabilities(7), sem_overview(7),
248 sysvipc(7)
249Linux man-pages 6.04 2023-03-30 semget(2)