| blob | 99ad0e7b90601c41cbf1eeb7969e07780c670e3e |
1 .\" $NetBSD: semctl.2,v 1.20 2010/03/22 19:30:55 joerg Exp $
2 .\"
3 .\" Copyright (c) 1995 Frank van der Linden
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. All advertising materials mentioning features or use of this software
15 .\" must display the following acknowledgement:
16 .\" This product includes software developed for the NetBSD Project
17 .\" by Frank van der Linden
18 .\" 4. The name of the author may not be used to endorse or promote products
19 .\" derived from this software without specific prior written permission
20 .\"
21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 .\"
32 .Dd August 25, 1999
33 .Dt SEMCTL 2
34 .Os
35 .Sh NAME
36 .Nm semctl
37 .Nd semaphore control operations
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In sys/sem.h
42 .Ft int
43 .Fn semctl "int semid" "int semnum" "int cmd" "..."
44 .Sh DESCRIPTION
45 The
46 .Fn semctl
47 system call provides a number of control operations on the semaphore specified
48 by
49 .Fa semnum
50 and
51 .Fa semid .
52 The operation to be performed is specified in
53 .Fa cmd
54 (see below).
55 The fourth argument is optional and depends upon the operation requested.
56 If required, it is a union of the following fields:
57 .Bd -literal
58 int val; /* value for SETVAL */
59 struct semid_ds *buf; /* buffer for IPC_{STAT,SET} */
60 u_short *array; /* array for GETALL \*[Am] SETALL */
61 .Ed
62 .Pp
63 The
64 .Sy semid_ds
65 structure used in the
66 .Dv IPC_SET
67 and
68 .Dv IPC_STAT
69 commands is defined in
70 .In sys/sem.h
71 and contains the following members:
72 .Bd -literal
73 struct ipc_perm sem_perm; /* operation permissions */
74 unsigned short sem_nsems; /* number of sems in set */
75 time_t sem_otime; /* last operation time */
76 time_t sem_ctime; /* last change time */
77 .Ed
78 .Pp
79 The
80 .Sy ipc_perm
81 structure used inside the
82 .Sy semid_ds
83 structure is defined in
84 .In sys/ipc.h
85 and contains the following members:
86 .Bd -literal
87 uid_t cuid; /* creator user id */
88 gid_t cgid; /* creator group id */
89 uid_t uid; /* user id */
90 gid_t gid; /* group id */
91 mode_t mode; /* permission (lower 9 bits) */
92 .Ed
93 .Pp
94 .Fn semctl
95 provides the following operations:
96 .Bl -tag -width IPC_RMIDX
97 .It Dv GETVAL
98 Return the value of the semaphore.
99 .It Dv SETVAL
100 Set the value of the semaphore to
101 .Fa arg.val ,
102 where
103 .Fa arg
104 is the fourth argument to
105 .Fn semctl .
106 .It Dv GETPID
107 Return the pid of the last process that did an operation on this semaphore.
108 .It Dv GETNCNT
109 Return the number of processes waiting to acquire the semaphore.
110 .It Dv GETZCNT
111 Return the number of processes waiting for the value of the semaphore to
112 reach 0.
113 .It Dv GETALL
114 Return the values of all the semaphores associated with
115 .Fa semid .
116 .It Dv SETALL
117 Set the values of all the semaphores that are associated with the semaphore
118 identifier
119 .Fa semid
120 to the corresponding values in
121 .Fa arg.array ,
122 where
123 .Fa arg
124 is the fourth argument to
125 .Fn semctl .
126 .It Dv IPC_STAT
127 Gather information about a semaphore and place the information in the
128 structure pointed to by
129 .Fa arg.buf ,
130 where
131 .Fa arg
132 is the fourth argument to
133 .Fn semctl .
134 .It Dv IPC_SET
135 Set the value of the
136 .Va sem_perm.uid ,
137 .Va sem_perm.gid
138 and
139 .Va sem_perm.mode
140 fields in the structure associated with the semaphore.
141 The values are taken from the corresponding fields in the structure
142 pointed to by
143 .Fa arg.buf ,
144 there
145 .Fa arg
146 is the fourth argument to
147 .Fn semctl .
148 This operation can only be executed by the super-user, or a process that
149 has an effective user id equal to either
150 .Va sem_perm.cuid
151 or
152 .Va sem_perm.uid
153 in the data structure associated with the semaphore.
154 .It Dv IPC_RMID
155 Remove the semaphores associated with
156 .Fa semid
157 from the system and destroy the data structures associated with it.
158 Only the super-user or a process with an effective uid equal to the
159 .Va sem_perm.cuid
160 or
161 .Va sem_perm.uid
162 values in the data structure associated with the semaphore can do this.
163 .El
164 .Pp
165 The permission to read or change a semaphore (see
166 .Xr semop 2 )
167 is determined by the
168 .Va sem_perm.mode
169 field in the same way as is
170 done with files (see
171 .Xr chmod 2 ) ,
172 but the effective uid can match either the
173 .Va sem_perm.cuid
174 field or the
175 .Va sem_perm.uid
176 field, and the
177 effective gid can match either
178 .Va sem_perm.cgid
179 or
180 .Va sem_perm.gid .
181 .Sh RETURN VALUES
182 For the
183 .Dv GETVAL ,
184 .Dv GETPID ,
185 .Dv GETNCNT ,
186 and
187 .Dv GETZCNT
188 operations,
189 .Fn semctl
190 returns one of the values described above if successful.
191 All other operations will make
192 .Fn semctl
193 return 0 if no errors occur.
194 Otherwise \-1 is returned and
195 .Va errno
196 set to reflect the error.
197 .Sh ERRORS
198 .Fn semctl
199 will fail if:
200 .Bl -tag -width Er
201 .It Bq Er EACCES
202 The caller has no operation permission for this semaphore.
203 .It Bq Er EFAULT
204 .Fa arg.buf
205 or
206 .Fa arg.array
207 specifies an invalid address.
208 .It Bq Er EINVAL
209 .Fa semid
210 is not a valid message semaphore identifier.
211 .Pp
212 .Va cmd
213 is not a valid command.
214 .It Bq Er EPERM
215 .Fa cmd
216 is equal to
217 .Dv IPC_SET
218 or
219 .Dv IPC_RMID
220 and the caller is not the super-user, nor does
221 the effective uid match either the
222 .Va sem_perm.uid
223 or
224 .Va sem_perm.cuid
225 fields of the data structure associated with the semaphore.
226 .It Bq Er ERANGE
227 .Fa cmd
228 is equal to
229 .Dv SETVAL
230 or
231 .Dv SETALL
232 and the value to be set is greater than the system semaphore maximum value.
233 .El
234 .Sh SEE ALSO
235 .Xr semget 2 ,
236 .Xr semop 2
237 .Sh STANDARDS
238 The
239 .Nm
240 system call conforms to
241 .St -xsh5 .
242 .Sh HISTORY
243 Semaphores appeared in the first release of
244 .At V .