1SEMCTL(3P) POSIX Programmer's Manual SEMCTL(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 semctl — XSI semaphore control operations
13
15 #include <sys/sem.h>
16 int semctl(int semid, int semnum, int cmd, ...);
18
20 The semctl() function operates on XSI semaphores (see the Base Defini‐
21 tions volume of POSIX.1‐2017, Section 4.17, Semaphore). It is unspeci‐
22 fied whether this function interoperates with the realtime interprocess
23 communication facilities defined in Section 2.8, Realtime.
24 The semctl() function provides a variety of semaphore control opera‐
26 tions as specified by cmd. The fourth argument is optional and depends
27 upon the operation requested. If required, it is of type union semun,
28 which the application shall explicitly declare:
29 union semun {
32 int val;
33 struct semid_ds *buf;
34 unsigned short *array;
35 } arg;
36 Each operation shall be performed atomically.
38 The following semaphore control operations as specified by cmd are exe‐
40 cuted with respect to the semaphore specified by semid and semnum. The
41 level of permission required for each operation is shown with each com‐
42 mand; see Section 2.7, XSI Interprocess Communication. The symbolic
43 names for the values of cmd are defined in the <sys/sem.h> header:
44 GETVAL Return the value of semval; see <sys/sem.h>. Requires read
46 permission.
47 SETVAL Set the value of semval to arg.val, where arg is the value
49 of the fourth argument to semctl(). When this command is
50 successfully executed, the semadj value corresponding to
51 the specified semaphore in all processes is cleared. Also,
52 the sem_ctime timestamp shall be set to the current time,
53 as described in Section 2.7.1, IPC General Description.
54 Requires alter permission; see Section 2.7, XSI Interpro‐
55 cess Communication.
56 GETPID Return the value of sempid. Requires read permission.
58 GETNCNT Return the value of semncnt. Requires read permission.
60 GETZCNT Return the value of semzcnt. Requires read permission.
62 The following values of cmd operate on each semval in the set of sema‐
64 phores:
65 GETALL Return the value of semval for each semaphore in the sema‐
67 phore set and place into the array pointed to by arg.array,
68 where arg is the fourth argument to semctl(). Requires
69 read permission.
70 SETALL Set the value of semval for each semaphore in the semaphore
72 set according to the array pointed to by arg.array, where
73 arg is the fourth argument to semctl(). When this command
74 is successfully executed, the semadj values corresponding
75 to each specified semaphore in all processes are cleared.
76 Also, the sem_ctime timestamp shall be set to the current
77 time, as described in Section 2.7.1, IPC General Descrip‐
78 tion. Requires alter permission.
79 The following values of cmd are also available:
81 IPC_STAT Place the current value of each member of the semid_ds data
83 structure associated with semid into the structure pointed
84 to by arg.buf, where arg is the fourth argument to sem‐
85 ctl(). The contents of this structure are defined in
86 <sys/sem.h>. Requires read permission.
87 IPC_SET Set the value of the following members of the semid_ds data
89 structure associated with semid to the corresponding value
90 found in the structure pointed to by arg.buf, where arg is
91 the fourth argument to semctl():
92 sem_perm.uid
95 sem_perm.gid
96 sem_perm.mode
97 The mode bits specified in Section 2.7.1, IPC General
99 Description are copied into the corresponding bits of the
100 sem_perm.mode associated with semid. The stored values of
101 any other bits are unspecified. The sem_ctime timestamp
102 shall be set to the current time, as described in Section
103 2.7.1, IPC General Description.
104 This command can only be executed by a process that has an
106 effective user ID equal to either that of a process with
107 appropriate privileges or to the value of sem_perm.cuid or
108 sem_perm.uid in the semid_ds data structure associated with
109 semid.
110 IPC_RMID Remove the semaphore identifier specified by semid from the
112 system and destroy the set of semaphores and semid_ds data
113 structure associated with it. This command can only be exe‐
114 cuted by a process that has an effective user ID equal to
115 either that of a process with appropriate privileges or to
116 the value of sem_perm.cuid or sem_perm.uid in the semid_ds
117 data structure associated with semid.
118
120 If successful, the value returned by semctl() depends on cmd as fol‐
121 lows:
122 GETVAL The value of semval.
124 GETPID The value of sempid.
126 GETNCNT The value of semncnt.
128 GETZCNT The value of semzcnt.
130 All others 0.
132 Otherwise, semctl() shall return -1 and set errno to indicate the
134 error.
135
137 The semctl() function shall fail if:
138 EACCES Operation permission is denied to the calling process; see Sec‐
140 tion 2.7, XSI Interprocess Communication.
141 EINVAL The value of semid is not a valid semaphore identifier, or the
143 value of semnum is less than 0 or greater than or equal to
144 sem_nsems, or the value of cmd is not a valid command.
145 EPERM The argument cmd is equal to IPC_RMID or IPC_SET and the effec‐
147 tive user ID of the calling process is not equal to that of a
148 process with appropriate privileges and it is not equal to the
149 value of sem_perm.cuid or sem_perm.uid in the data structure
150 associated with semid.
151 ERANGE The argument cmd is equal to SETVAL or SETALL and the value to
153 which semval is to be set is greater than the system-imposed
154 maximum.
155 The following sections are informative.
157
159 Refer to semop().
160
162 The fourth parameter in the SYNOPSIS section is now specified as "..."
163 in order to avoid a clash with the ISO C standard when referring to the
164 union semun (as defined in Issue 3) and for backwards-compatibility.
165 The POSIX Realtime Extension defines alternative interfaces for inter‐
167 process communication. Application developers who need to use IPC
168 should design their applications so that modules using the IPC routines
169 described in Section 2.7, XSI Interprocess Communication can be easily
170 modified to use the alternative interfaces.
171
173 None.
174
176 None.
177
179 Section 2.7, XSI Interprocess Communication, Section 2.8, Realtime,
180 semget(), semop(), sem_close(), sem_destroy(), sem_getvalue(),
181 sem_init(), sem_open(), sem_post(), sem_trywait(), sem_unlink()
182 The Base Definitions volume of POSIX.1‐2017, Section 4.17, Semaphore,
184 <sys_sem.h>
185
187 Portions of this text are reprinted and reproduced in electronic form
188 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
189 table Operating System Interface (POSIX), The Open Group Base Specifi‐
190 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
191 Electrical and Electronics Engineers, Inc and The Open Group. In the
192 event of any discrepancy between this version and the original IEEE and
193 The Open Group Standard, the original IEEE and The Open Group Standard
194 is the referee document. The original Standard can be obtained online
195 at http://www.opengroup.org/unix/online.html .
196 Any typographical or formatting errors that appear in this page are
198 most likely to have been introduced during the conversion of the source
199 files to man page format. To report such errors, see https://www.ker‐
200 nel.org/doc/man-pages/reporting_bugs.html .
201IEEE/The Open Group 2017 SEMCTL(3P)