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

NAME

6       semctl - System V semaphore control operations
7

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

CONFORMING TO

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

NOTES

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

EXAMPLES

320       See shmop(2).
321

SEE ALSO

323       ipc(2),   semget(2),   semop(2),   capabilities(7),    sem_overview(7),
324       sysvipc(7)
325

COLOPHON

327       This  page  is  part of release 5.07 of the Linux man-pages project.  A
328       description of the project, information about reporting bugs,  and  the
329       latest     version     of     this    page,    can    be    found    at
330       https://www.kernel.org/doc/man-pages/.
331
332
333
334Linux                             2020-04-11                         SEMCTL(2)
Impressum