1.\" 2.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> 3.\" 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.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd July 9, 2020 27.Dt SEMCTL 2 28.Os 29.Sh NAME 30.Nm semctl 31.Nd control operations on a semaphore set 32.Sh LIBRARY 33.Lb libc 34.Sh SYNOPSIS 35.In sys/types.h 36.In sys/ipc.h 37.In sys/sem.h 38.Ft int 39.Fn semctl "int semid" "int semnum" "int cmd" ... 40.Sh DESCRIPTION 41The 42.Fn semctl 43system call 44performs the operation indicated by 45.Fa cmd 46on the semaphore set indicated by 47.Fa semid . 48A fourth argument, a 49.Fa "union semun arg" , 50is required for certain values of 51.Fa cmd . 52For the commands that use the 53.Fa arg 54argument, 55.Fa "union semun" 56must be defined as follows: 57.Bd -literal 58union semun { 59 int val; /* value for SETVAL */ 60 struct semid_ds *buf; /* buffer for IPC_STAT & IPC_SET */ 61 u_short *array; /* array for GETALL & SETALL */ 62}; 63.Ed 64Non-portable software may define 65.Dv _WANT_SEMUN 66before including 67.Pa sys/sem.h 68to use the system definition of 69.Fa "union semun" . 70.Pp 71Commands are performed as follows: 72.\" 73.\" This section based on Stevens, _Advanced Programming in the UNIX 74.\" Environment_. 75.\" 76.Bl -tag -width IPC_RMIDXXX 77.It Dv IPC_STAT 78Fetch the semaphore set's 79.Fa "struct semid_ds" , 80storing it in the memory pointed to by 81.Fa arg.buf . 82.It Dv IPC_SET 83Changes the 84.Fa sem_perm.uid , 85.Fa sem_perm.gid , 86and 87.Fa sem_perm.mode 88members of the semaphore set's 89.Fa "struct semid_ds" 90to match those of the struct pointed to by 91.Fa arg.buf . 92The calling process's effective uid must 93match either 94.Fa sem_perm.uid 95or 96.Fa sem_perm.cuid , 97or it must have superuser privileges. 98.It IPC_RMID 99Immediately removes the semaphore set from the system. 100The calling 101process's effective uid must equal the semaphore set's 102.Fa sem_perm.uid 103or 104.Fa sem_perm.cuid , 105or the process must have superuser privileges. 106.It Dv GETVAL 107Return the value of semaphore number 108.Fa semnum . 109.It Dv SETVAL 110Set the value of semaphore number 111.Fa semnum 112to 113.Fa arg.val . 114Outstanding adjust on exit values for this semaphore in any process 115are cleared. 116.It Dv GETPID 117Return the pid of the last process to perform an operation on 118semaphore number 119.Fa semnum . 120.It Dv GETNCNT 121Return the number of processes waiting for semaphore number 122.Fa semnum Ns 's 123value to become greater than its current value. 124.It Dv GETZCNT 125Return the number of processes waiting for semaphore number 126.Fa semnum Ns 's 127value to become 0. 128.It Dv GETALL 129Fetch the value of all of the semaphores in the set into the 130array pointed to by 131.Fa arg.array . 132.It Dv SETALL 133Set the values of all of the semaphores in the set to the values 134in the array pointed to by 135.Fa arg.array . 136Outstanding adjust on exit values for all semaphores in this set, 137in any process are cleared. 138.El 139.Pp 140The 141.Vt "struct semid_ds" 142is defined as follows: 143.\" 144.\" Taken straight from <sys/sem.h>. 145.\" 146.Bd -literal 147struct semid_ds { 148 struct ipc_perm sem_perm; /* operation permission struct */ 149 u_short sem_nsems; /* number of sems in set */ 150 time_t sem_otime; /* last operation time */ 151 time_t sem_ctime; /* last change time */ 152 /* Times measured in secs since */ 153 /* 00:00:00 GMT, Jan. 1, 1970 */ 154}; 155.Ed 156.Sh RETURN VALUES 157On success, when 158.Fa cmd 159is one of 160.Dv GETVAL , GETPID , GETNCNT 161or 162.Dv GETZCNT , 163.Fn semctl 164returns the corresponding value; otherwise, 0 is returned. 165On failure, -1 is returned, and 166.Va errno 167is set to indicate the error. 168.Sh ERRORS 169The 170.Fn semctl 171system call 172will fail if: 173.Bl -tag -width Er 174.It Bq Er EINVAL 175No semaphore set corresponds to 176.Fa semid . 177.It Bq Er EINVAL 178The 179.Fa semnum 180argument 181is not in the range of valid semaphores for given semaphore set. 182.It Bq Er EPERM 183The calling process's effective uid does not match the uid of 184the semaphore set's owner or creator. 185.It Bq Er EACCES 186Permission denied due to mismatch between operation and mode of 187semaphore set. 188.It Bq Er ERANGE 189.Dv SETVAL 190or 191.Dv SETALL 192attempted to set a semaphore outside the allowable range 193.Bq 0 .. Dv SEMVMX . 194.El 195.Sh SEE ALSO 196.Xr semget 2 , 197.Xr semop 2 198.Sh BUGS 199.Dv SETALL 200may update some semaphore elements before returning an error. 201