1SEMCTL(2)                  Linux Programmer's Manual                 SEMCTL(2)
2
3
4

NAME

6       semctl - System V semaphore control operations
7

SYNOPSIS

9       #include <sys/sem.h>
10
11       int semctl(int semid, int semnum, int cmd, ...);
12

DESCRIPTION

14       semctl()  performs  the  control operation specified by cmd on the Sys‐
15       tem V semaphore set identified by semid, or on the semnum-th  semaphore
16       of that set.  (The semaphores in a set are numbered starting at 0.)
17
18       This  function  has  three  or  four arguments, depending on cmd.  When
19       there are four, the fourth has the type union semun.  The calling  pro‐
20       gram must define this union as follows:
21
22           union semun {
23               int              val;    /* Value for SETVAL */
24               struct semid_ds *buf;    /* Buffer for IPC_STAT, IPC_SET */
25               unsigned short  *array;  /* Array for GETALL, SETALL */
26               struct seminfo  *__buf;  /* Buffer for IPC_INFO
27                                           (Linux-specific) */
28           };
29
30       The semid_ds data structure is defined in <sys/sem.h> as follows:
31
32           struct semid_ds {
33               struct ipc_perm sem_perm;  /* Ownership and permissions */
34               time_t          sem_otime; /* Last semop time */
35               time_t          sem_ctime; /* Creation time/time of last
36                                             modification via semctl() */
37               unsigned long   sem_nsems; /* No. of semaphores in set */
38           };
39
40       The fields of the semid_ds structure are as follows:
41
42       sem_perm   This is an ipc_perm structure (see below) that specifies the
43                  access permissions on the semaphore set.
44
45       sem_otime  Time of last semop(2) system call.
46
47       sem_ctime  Time of creation of semaphore set or time of  last  semctl()
48                  IPCSET, SETVAL, or SETALL operation.
49
50       sem_nsems  Number  of semaphores in the set.  Each semaphore of the set
51                  is referenced by a nonnegative integer  ranging  from  0  to
52                  sem_nsems-1.
53
54       The  ipc_perm  structure  is defined as follows (the highlighted fields
55       are settable using IPC_SET):
56
57           struct ipc_perm {
58               key_t          __key; /* Key supplied to semget(2) */
59               uid_t          uid;   /* Effective UID of owner */
60               gid_t          gid;   /* Effective GID of owner */
61               uid_t          cuid;  /* Effective UID of creator */
62               gid_t          cgid;  /* Effective GID of creator */
63               unsigned short mode;  /* Permissions */
64               unsigned short __seq; /* Sequence number */
65           };
66
67       The least significant 9 bits of the mode field of the  ipc_perm  struc‐
68       ture  define the access permissions for the shared memory segment.  The
69       permission bits are as follows:
70
71       0400   Read by user
72       0200   Write by user
73       0040   Read by group
74       0020   Write by group
75       0004   Read by others
76       0002   Write by others
77
78       In effect, "write" means "alter" for a semaphore set.  Bits 0100, 0010,
79       and 0001 (the execute bits) are unused by the system.
80
81       Valid values for cmd are:
82
83       IPC_STAT
84              Copy  information from the kernel data structure associated with
85              semid into the semid_ds structure pointed to  by  arg.buf.   The
86              argument  semnum is ignored.  The calling process must have read
87              permission on the semaphore set.
88
89       IPC_SET
90              Write the values of  some  members  of  the  semid_ds  structure
91              pointed  to  by  arg.buf to the kernel data structure associated
92              with this semaphore set, updating also its sem_ctime member.
93
94              The  following   members   of   the   structure   are   updated:
95              sem_perm.uid,  sem_perm.gid,  and  (the least significant 9 bits
96              of) sem_perm.mode.
97
98              The effective UID of the calling process must  match  the  owner
99              (sem_perm.uid)  or creator (sem_perm.cuid) of the semaphore set,
100              or the caller must be privileged.  The argument  semnum  is  ig‐
101              nored.
102
103       IPC_RMID
104              Immediately  remove  the  semaphore set, awakening all processes
105              blocked in semop(2) calls on the set (with an error  return  and
106              errno  set  to  EIDRM).   The  effective  user ID of the calling
107              process must match the creator or owner of the semaphore set, or
108              the caller must be privileged.  The argument semnum is ignored.
109
110       IPC_INFO (Linux-specific)
111              Return information about system-wide semaphore limits and param‐
112              eters in the structure pointed to by arg.__buf.  This  structure
113              is  of  type  seminfo, defined in <sys/sem.h> if the _GNU_SOURCE
114              feature test macro is defined:
115
116                  struct  seminfo {
117                      int semmap;  /* Number of entries in semaphore
118                                      map; unused within kernel */
119                      int semmni;  /* Maximum number of semaphore sets */
120                      int semmns;  /* Maximum number of semaphores in all
121                                      semaphore sets */
122                      int semmnu;  /* System-wide maximum number of undo
123                                      structures; unused within kernel */
124                      int semmsl;  /* Maximum number of semaphores in a
125                                      set */
126                      int semopm;  /* Maximum number of operations for
127                                      semop(2) */
128                      int semume;  /* Maximum number of undo entries per
129                                      process; unused within kernel */
130                      int semusz;  /* Size of struct sem_undo */
131                      int semvmx;  /* Maximum semaphore value */
132                      int semaem;  /* Max. value that can be recorded for
133                                      semaphore adjustment (SEM_UNDO) */
134                  };
135
136              The semmsl, semmns, semopm, and semmni settings can  be  changed
137              via /proc/sys/kernel/sem; see proc(5) for details.
138
139       SEM_INFO (Linux-specific)
140              Return  a  seminfo  structure containing the same information as
141              for IPC_INFO, except that the following fields are returned with
142              information  about  system resources consumed by semaphores: the
143              semusz field returns the number of semaphore sets that currently
144              exist on the system; and the semaem field returns the total num‐
145              ber of semaphores in all semaphore sets on the system.
146
147       SEM_STAT (Linux-specific)
148              Return a semid_ds structure as for IPC_STAT.  However, the semid
149              argument  is  not  a  semaphore identifier, but instead an index
150              into the kernel's  internal  array  that  maintains  information
151              about all semaphore sets on the system.
152
153       SEM_STAT_ANY (Linux-specific, since Linux 4.17)
154              Return   a   semid_ds   structure  as  for  SEM_STAT.   However,
155              sem_perm.mode is not checked for read access for  semid  meaning
156              that  any  user  can employ this operation (just as any user may
157              read /proc/sysvipc/sem to obtain the same information).
158
159       GETALL Return semval (i.e., the current value) for  all  semaphores  of
160              the  set  into  arg.array.  The argument semnum is ignored.  The
161              calling process must have read permission on the semaphore set.
162
163       GETNCNT
164              Return the semncnt value for the semnum-th semaphore of the  set
165              (i.e., the number of processes waiting for the semaphore's value
166              to increase).  The calling process must have read permission  on
167              the semaphore set.
168
169       GETPID Return  the sempid value for the semnum-th semaphore of the set.
170              This is the PID of the process that last performed an  operation
171              on  that  semaphore  (but  see NOTES).  The calling process must
172              have read permission on the semaphore set.
173
174       GETVAL Return semval (i.e., the semaphore value) for the semnum-th sem‐
175              aphore  of  the set.  The calling process must have read permis‐
176              sion on the semaphore set.
177
178       GETZCNT
179              Return the semzcnt value for the semnum-th semaphore of the  set
180              (i.e.,  the  number of processes waiting for the semaphore value
181              to become 0).  The calling process must have read permission  on
182              the semaphore set.
183
184       SETALL Set  the  semval  values  for  all  semaphores  of the set using
185              arg.array, updating also the sem_ctime member  of  the  semid_ds
186              structure  associated with the set.  Undo entries (see semop(2))
187              are cleared for altered semaphores in  all  processes.   If  the
188              changes  to semaphore values would permit blocked semop(2) calls
189              in other processes to proceed, then those  processes  are  woken
190              up.   The  argument semnum is ignored.  The calling process must
191              have alter (write) permission on the semaphore set.
192
193       SETVAL Set the semaphore value (semval) to arg.val  for  the  semnum-th
194              semaphore  of the set, updating also the sem_ctime member of the
195              semid_ds structure associated with the set.   Undo  entries  are
196              cleared for altered semaphores in all processes.  If the changes
197              to semaphore values would permit blocked semop(2) calls in other
198              processes  to  proceed,  then those processes are woken up.  The
199              calling process must have alter permission on the semaphore set.
200

RETURN VALUE

202       On success, semctl() returns a nonnegative value depending  on  cmd  as
203       follows:
204
205       GETNCNT
206              the value of semncnt.
207
208       GETPID the value of sempid.
209
210       GETVAL the value of semval.
211
212       GETZCNT
213              the value of semzcnt.
214
215       IPC_INFO
216              the index of the highest used entry in the kernel's internal ar‐
217              ray recording information about all semaphore sets.   (This  in‐
218              formation can be used with repeated SEM_STAT or SEM_STAT_ANY op‐
219              erations to obtain information about all semaphore sets  on  the
220              system.)
221
222       SEM_INFO
223              as for IPC_INFO.
224
225       SEM_STAT
226              the  identifier  of  the  semaphore set whose index was given in
227              semid.
228
229       SEM_STAT_ANY
230              as for SEM_STAT.
231
232       All other cmd values return 0 on success.
233
234       On failure, semctl() returns -1 and sets errno to indicate the error.
235

ERRORS

237       EACCES The argument cmd has one of the values GETALL,  GETPID,  GETVAL,
238              GETNCNT,  GETZCNT,  IPC_STAT, SEM_STAT, SEM_STAT_ANY, SETALL, or
239              SETVAL and the calling process does not have the  required  per‐
240              missions   on   the   semaphore   set  and  does  not  have  the
241              CAP_IPC_OWNER capability in the user namespace that governs  its
242              IPC namespace.
243
244       EFAULT The address pointed to by arg.buf or arg.array isn't accessible.
245
246       EIDRM  The semaphore set was removed.
247
248       EINVAL Invalid  value  for cmd or semid.  Or: for a SEM_STAT operation,
249              the index value specified in semid referred  to  an  array  slot
250              that is currently unused.
251
252       EPERM  The  argument  cmd has the value IPC_SET or IPC_RMID but the ef‐
253              fective user ID of the calling process is not  the  creator  (as
254              found  in sem_perm.cuid) or the owner (as found in sem_perm.uid)
255              of the  semaphore  set,  and  the  process  does  not  have  the
256              CAP_SYS_ADMIN capability.
257
258       ERANGE The argument cmd has the value SETALL or SETVAL and the value to
259              which semval is to be set (for some semaphore  of  the  set)  is
260              less than 0 or greater than the implementation limit SEMVMX.
261

CONFORMING TO

263       POSIX.1-2001, POSIX.1-2008, SVr4.
264
265       POSIX.1 specifies the sem_nsems field of the semid_ds structure as hav‐
266       ing the type unsigned short, and the field is so defined on most  other
267       systems.   It  was also so defined on Linux 2.2 and earlier, but, since
268       Linux 2.4, the field has the type unsigned long.
269

NOTES

271       The IPC_INFO, SEM_STAT, and SEM_INFO operations are used by the ipcs(1)
272       program  to  provide information on allocated resources.  In the future
273       these may modified or moved to a /proc filesystem interface.
274
275       Various fields in a struct semid_ds were typed as short under Linux 2.2
276       and have become long under Linux 2.4.  To take advantage of this, a re‐
277       compilation under glibc-2.1.91 or later should  suffice.   (The  kernel
278       distinguishes old and new calls by an IPC_64 flag in cmd.)
279
280       In  some  earlier  versions  of  glibc,  the semun union was defined in
281       <sys/sem.h>, but POSIX.1 requires that the caller  define  this  union.
282       On  versions  of  glibc  where  this  union  is  not defined, the macro
283       _SEM_SEMUN_UNDEFINED is defined in <sys/sem.h>.
284
285       The following system limit on semaphore sets affects a semctl() call:
286
287       SEMVMX Maximum value for semval: implementation dependent (32767).
288
289       For greater portability, it is best to always call semctl()  with  four
290       arguments.
291
292   The sempid value
293       POSIX.1 defines sempid as the "process ID of [the] last operation" on a
294       semaphore, and explicitly notes that this value is set by a  successful
295       semop(2) call, with the implication that no other interface affects the
296       sempid value.
297
298       While  some  implementations  conform  to  the  behavior  specified  in
299       POSIX.1,  others  do  not.   (The fault here probably lies with POSIX.1
300       inasmuch as it likely failed to capture the full range of existing  im‐
301       plementation  behaviors.)   Various  other  implementations also update
302       sempid for the other operations that update the value of  a  semaphore:
303       the  SETVAL and SETALL operations, as well as the semaphore adjustments
304       performed on process termination as a consequence of  the  use  of  the
305       SEM_UNDO flag (see semop(2)).
306
307       Linux  also  updates sempid for SETVAL operations and semaphore adjust‐
308       ments.  However, somewhat inconsistently, up  to  and  including  Linux
309       4.5,  the kernel did not update sempid for SETALL operations.  This was
310       rectified in Linux 4.6.
311

EXAMPLES

313       See shmop(2).
314

SEE ALSO

316       ipc(2),   semget(2),   semop(2),   capabilities(7),    sem_overview(7),
317       sysvipc(7)
318

COLOPHON

320       This  page  is  part of release 5.13 of the Linux man-pages project.  A
321       description of the project, information about reporting bugs,  and  the
322       latest     version     of     this    page,    can    be    found    at
323       https://www.kernel.org/doc/man-pages/.
324
325
326
327Linux                             2021-03-22                         SEMCTL(2)
Impressum