1.\" $NetBSD: semctl.2,v 1.11 2002/02/08 01:28:21 ross 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.Fd #include \*[Lt]sys/sem.h\*[Gt] 42.Ft int 43.Fn semctl "int semid" "int semnum" "int cmd" "..." 44.Sh DESCRIPTION 45The 46.Fn semctl 47system call provides a number of control operations on the semaphore specified 48by 49.Fa semnum 50and 51.Fa semid . 52The operation to be performed is specified in 53.Fa cmd 54(see below). 55The fourth argument is optional and depends upon the opration requested. 56If 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 63The 64.Sy semid_ds 65structure used in the 66.Dv IPC_SET 67and 68.Dv IPC_STAT 69commands is defined in 70.Aq Pa sys/sem.h 71and 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 79The 80.Sy ipc_perm 81structure used inside the 82.Sy semid_ds 83structure is defined in 84.Aq Pa sys/ipc.h 85and 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 95provides the following operations: 96.Bl -tag -width IPC_RMIDX 97.It Dv GETVAL 98Return the value of the semaphore. 99.It Dv SETVAL 100Set the value of the semaphore to 101.Fa arg.val , 102where 103.Fa arg 104is the fourth arument to 105.Fn semctl . 106.It Dv GETPID 107Return the pid of the last process that did an operation on this semaphore. 108.It Dv GETNCNT 109Return the number of processes waiting to acquire the semaphore. 110.It Dv GETZCNT 111Return the number of processes waiting for the value of the semaphore to 112reach 0. 113.It Dv GETALL 114Return the values of all the semaphores associated with 115.Fa semid . 116.It Dv SETALL 117Set the values of all the semaphores that are associated with the semaphore 118identifier 119.Fa semid 120to the corresponding values in 121.Fa arg.array , 122where 123.Fa arg 124is the fourth argument to 125.Fn semctl . 126.It Dv IPC_STAT 127Gather information about a semaphore and place the information in the 128structure pointed to by 129.Fa arg.buf , 130where 131.Fa arg 132is the fourth argument to 133.Fn semctl . 134.It Dv IPC_SET 135Set the value of the 136.Va sem_perm.uid , 137.Va sem_perm.gid 138and 139.Va sem_perm.mode 140fields in the structure associated with the semaphore. 141The values are taken from the corresponding fields in the structure 142pointed to by 143.Fa arg.buf , 144there 145.Fa arg 146is the fourth argument to 147.Fn semctl . 148This operation can only be executed by the super-user, or a process that 149has an effective user id equal to either 150.Va sem_perm.cuid 151or 152.Va sem_perm.uid 153in the data structure associated with the message queue. 154.It Dv IPC_RMID 155Remove the semaphores associated with 156.Fa semid 157from the system and destroy the data structures associated with it. Only the 158super-user or a process with an effective uid equal to the 159.Va sem_perm.cuid 160or 161.Va sem_perm.uid 162values in the data structure associated with the semaphore can do this. 163.El 164.Pp 165The permission to read or change a message queue (see 166.Xr semop 2 ) 167is determined by the 168.Va sem_perm.mode 169field in the same way as is 170done with files (see 171.Xr chmod 2 ) , 172but the effective uid can match either the 173.Va sem_perm.cuid 174field or the 175.Va sem_perm.uid 176field, and the 177effective gid can match either 178.Va sem_perm.cgid 179or 180.Va sem_perm.gid . 181.Sh RETURN VALUES 182For the 183.Dv GETVAL , 184.Dv GETPID , 185.Dv GETNCNT , 186and 187.Dv GETZCNT 188operations, 189.Fn semctl 190returns one of the values described above if successful. All other operations 191will make 192.Fn semctl 193return 0 if no errors occur. Otherwise -1 is returned and 194.Va errno 195set to reflect the error. 196.Sh ERRORS 197.Fn semctl 198will fail if: 199.Bl -tag -width Er 200.It Bq Er EPERM 201.Fa cmd 202is equal to 203.Dv IPC_SET 204or 205.Dv IPC_RMID 206and the caller is not the super-user, nor does 207the effective uid match either the 208.Va sem_perm.uid 209or 210.Va sem_perm.cuid 211fields of the data structure associated with the message queue. 212.It Bq Er EACCES 213The caller has no operation permission for this semaphore. 214.It Bq Er EINVAL 215.Fa semid 216is not a valid message semaphore identifier. 217.Pp 218.Va cmd 219is not a valid command. 220.It Bq Er EFAULT 221.Fa arg.buf 222or 223.Fa arg.array 224specifies an invalid address. 225.El 226.Sh SEE ALSO 227.Xr semget 2 , 228.Xr semop 2 229.Sh STANDARDS 230The 231.Nm 232system call conforms to 233.St -xsh5 . 234.Sh HISTORY 235Semaphores appeared in the first release of 236.At V . 237