1.\" $NetBSD: semctl.2,v 1.13 2002/10/02 10:42:34 wiz 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 operation 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 argument 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. 158Only the super-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. 191All other operations will make 192.Fn semctl 193return 0 if no errors occur. 194Otherwise -1 is returned and 195.Va errno 196set to reflect the error. 197.Sh ERRORS 198.Fn semctl 199will fail if: 200.Bl -tag -width Er 201.It Bq Er EPERM 202.Fa cmd 203is equal to 204.Dv IPC_SET 205or 206.Dv IPC_RMID 207and the caller is not the super-user, nor does 208the effective uid match either the 209.Va sem_perm.uid 210or 211.Va sem_perm.cuid 212fields of the data structure associated with the message queue. 213.It Bq Er EACCES 214The caller has no operation permission for this semaphore. 215.It Bq Er EINVAL 216.Fa semid 217is not a valid message semaphore identifier. 218.Pp 219.Va cmd 220is not a valid command. 221.It Bq Er EFAULT 222.Fa arg.buf 223or 224.Fa arg.array 225specifies an invalid address. 226.El 227.Sh SEE ALSO 228.Xr semget 2 , 229.Xr semop 2 230.Sh STANDARDS 231The 232.Nm 233system call conforms to 234.St -xsh5 . 235.Sh HISTORY 236Semaphores appeared in the first release of 237.At V . 238