1SEMCTL(3P)                 POSIX Programmer's Manual                SEMCTL(3P)
2
3
4

PROLOG

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

NAME

12       semctl - XSI semaphore control operations
13

SYNOPSIS

15       #include <sys/sem.h>
16
17       int semctl(int semid, int semnum, int cmd, ...);
18
19

DESCRIPTION

21       The semctl() function operates on XSI semaphores (see the Base  Defini‐
22       tions  volume of IEEE Std 1003.1-2001, Section 4.15, Semaphore).  It is
23       unspecified whether  this  function  interoperates  with  the  realtime
24       interprocess communication facilities defined in Realtime .
25
26       The  semctl()  function  provides a variety of semaphore control opera‐
27       tions as specified by cmd. The fourth argument is optional and  depends
28       upon  the  operation requested. If required, it is of type union semun,
29       which the application shall explicitly declare:
30
31
32              union semun {
33                  int val;
34                  struct semid_ds *buf;
35                  unsigned short  *array;
36              } arg;
37
38       The following semaphore control operations as specified by cmd are exe‐
39       cuted  with respect to the semaphore specified by semid and semnum. The
40       level of permission required for each operation is shown with each com‐
41       mand;  see  XSI Interprocess Communication . The symbolic names for the
42       values of cmd are defined in the <sys/sem.h> header:
43
44       GETVAL Return the value of semval; see <sys/sem.h>. Requires read  per‐
45              mission.
46
47       SETVAL Set  the  value  of semval to arg.val, where arg is the value of
48              the fourth argument to semctl(). When this command  is  success‐
49              fully  executed, the semadj value corresponding to the specified
50              semaphore in all processes is cleared.  Requires  alter  permis‐
51              sion; see XSI Interprocess Communication .
52
53       GETPID Return the value of sempid. Requires read permission.
54
55       GETNCNT
56              Return the value of semncnt. Requires read permission.
57
58       GETZCNT
59              Return the value of semzcnt. Requires read permission.
60
61
62       The  following values of cmd operate on each semval in the set of sema‐
63       phores:
64
65       GETALL Return the value of semval for each semaphore in  the  semaphore
66              set  and place into the array pointed to by arg.array, where arg
67              is the fourth argument to semctl().  Requires read permission.
68
69       SETALL Set the value of semval for each semaphore in the semaphore  set
70              according to the array pointed to by arg.array, where arg is the
71              fourth argument to semctl(). When this command  is  successfully
72              executed, the semadj values corresponding to each specified sem‐
73              aphore in all processes are cleared.  Requires alter permission.
74
75
76       The following values of cmd are also available:
77
78       IPC_STAT
79              Place the current value of each  member  of  the  semid_ds  data
80              structure associated with semid into the structure pointed to by
81              arg.buf, where arg is the fourth argument to semctl(). The  con‐
82              tents  of  this  structure  are defined in <sys/sem.h>. Requires
83              read permission.
84
85       IPC_SET
86              Set the value of the following  members  of  the  semid_ds  data
87              structure associated with semid to the corresponding value found
88              in the structure pointed to by arg.buf, where arg is the  fourth
89              argument to semctl():
90
91
92              sem_perm.uid
93              sem_perm.gid
94              sem_perm.mode
95
96       The  mode bits specified in IPC General Description are copied into the
97       corresponding bits of the sem_perm.mode  associated  with  semid.   The
98       stored values of any other bits are unspecified.
99
100       This  command  can  only be executed by a process that has an effective
101       user ID equal to either that of a process with  appropriate  privileges
102       or  to  the value of sem_perm.cuid or sem_perm.uid in the semid_ds data
103       structure associated with semid.
104
105       IPC_RMID
106              Remove the semaphore identifier specified by semid from the sys‐
107              tem  and  destroy the set of semaphores and semid_ds data struc‐
108              ture associated with it. This command can only be executed by  a
109              process  that has an effective user ID equal to either that of a
110              process  with  appropriate  privileges  or  to  the   value   of
111              sem_perm.cuid  or  sem_perm.uid  in  the semid_ds data structure
112              associated with semid.
113
114

RETURN VALUE

116       If successful, the value returned by semctl() depends on  cmd  as  fol‐
117       lows:
118
119       GETVAL The value of semval.
120
121       GETPID The value of sempid.
122
123       GETNCNT
124              The value of semncnt.
125
126       GETZCNT
127              The value of semzcnt.
128
129       All others
130              0.
131
132
133       Otherwise,  semctl()  shall  return  -1  and  set errno to indicate the
134       error.
135

ERRORS

137       The semctl() function shall fail if:
138
139       EACCES Operation permission is denied to the calling process;  see  XSI
140              Interprocess Communication .
141
142       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
146       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
152       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
156
157       The following sections are informative.
158

EXAMPLES

160       None.
161

APPLICATION USAGE

163       The  fourth parameter in the SYNOPSIS section is now specified as "..."
164       in order to avoid a clash with the ISO C standard when referring to the
165       union semun (as defined in Issue 3) and for backwards-compatibility.
166
167       The  POSIX Realtime Extension defines alternative interfaces for inter‐
168       process communication. Application  developers  who  need  to  use  IPC
169       should design their applications so that modules using the IPC routines
170       described in XSI Interprocess Communication can be easily  modified  to
171       use the alternative interfaces.
172

RATIONALE

174       None.
175

FUTURE DIRECTIONS

177       None.
178

SEE ALSO

180       XSI    Interprocess   Communication,   Realtime,   semget(),   semop(),
181       sem_close(),  sem_destroy(),  sem_getvalue(),  sem_init(),  sem_open(),
182       sem_post(),  sem_unlink(),  sem_wait(),  the Base Definitions volume of
183       IEEE Std 1003.1-2001, <sys/sem.h>
184
186       Portions of this text are reprinted and reproduced in  electronic  form
187       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
188       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
189       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
190       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
191       event of any discrepancy between this version and the original IEEE and
192       The Open Group Standard, the original IEEE and The Open Group  Standard
193       is  the  referee document. The original Standard can be obtained online
194       at http://www.opengroup.org/unix/online.html .
195
196
197
198IEEE/The Open Group                  2003                           SEMCTL(3P)
Impressum