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