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

NAME

6       semctl - System V semaphore control operations
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/sem.h>
13
14       int semctl(int semid, int semnum, int cmd, ...);
15

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

VERSIONS

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
271   The sempid value
272       POSIX.1 defines sempid as the "process ID of [the] last operation" on a
273       semaphore,  and explicitly notes that this value is set by a successful
274       semop(2) call, with the implication that no other interface affects the
275       sempid value.
276
277       While  some  implementations  conform  to  the  behavior  specified  in
278       POSIX.1, others do not.  (The fault here  probably  lies  with  POSIX.1
279       inasmuch  as it likely failed to capture the full range of existing im‐
280       plementation behaviors.)  Various  other  implementations  also  update
281       sempid  for  the other operations that update the value of a semaphore:
282       the SETVAL and SETALL operations, as well as the semaphore  adjustments
283       performed  on  process  termination  as a consequence of the use of the
284       SEM_UNDO flag (see semop(2)).
285
286       Linux also updates sempid for SETVAL operations and  semaphore  adjust‐
287       ments.   However,  somewhat  inconsistently,  up to and including Linux
288       4.5, the kernel did not update sempid for SETALL operations.  This  was
289       rectified in Linux 4.6.
290

STANDARDS

292       POSIX.1-2008.
293

HISTORY

295       POSIX.1-2001, SVr4.
296
297       Various fields in a struct semid_ds were typed as short under Linux 2.2
298       and have become long under Linux 2.4.  To take advantage of this, a re‐
299       compilation  under  glibc-2.1.91  or later should suffice.  (The kernel
300       distinguishes old and new calls by an IPC_64 flag in cmd.)
301
302       In some earlier versions of glibc,  the  semun  union  was  defined  in
303       <sys/sem.h>,  but  POSIX.1  requires that the caller define this union.
304       On versions of glibc  where  this  union  is  not  defined,  the  macro
305       _SEM_SEMUN_UNDEFINED is defined in <sys/sem.h>.
306

NOTES

308       The IPC_INFO, SEM_STAT, and SEM_INFO operations are used by the ipcs(1)
309       program to provide information on allocated resources.  In  the  future
310       these may modified or moved to a /proc filesystem interface.
311
312       The following system limit on semaphore sets affects a semctl() call:
313
314       SEMVMX Maximum value for semval: implementation dependent (32767).
315
316       For  greater  portability, it is best to always call semctl() with four
317       arguments.
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
326
327
328Linux man-pages 6.05              2023-03-30                         semctl(2)
Impressum