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

NAME

6       semctl - XSI semaphore control operations
7

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

131       The semctl() function shall fail if:
132
133       EACCES Operation  permission  is denied to the calling process; see XSI
134              Interprocess Communication .
135
136       EINVAL The value of semid is not a valid semaphore identifier,  or  the
137              value  of  semnum  is  less  than  0 or greater than or equal to
138              sem_nsems, or the value of cmd is not a valid command.
139
140       EPERM  The argument cmd is equal to IPC_RMID or IPC_SET and the  effec‐
141              tive  user  ID  of the calling process is not equal to that of a
142              process with appropriate privileges and it is not equal  to  the
143              value  of  sem_perm.cuid  or  sem_perm.uid in the data structure
144              associated with semid.
145
146       ERANGE The argument cmd is equal to SETVAL or SETALL and the  value  to
147              which  semval  is  to  be set is greater than the system-imposed
148              maximum.
149
150
151       The following sections are informative.
152

EXAMPLES

154       None.
155

APPLICATION USAGE

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

RATIONALE

168       None.
169

FUTURE DIRECTIONS

171       None.
172

SEE ALSO

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