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 September 12, 1995 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" 58is defined as follows: 59.\" 60.\" From <sys/sem.h>: 61.\" 62.Bd -literal 63union semun { 64 int val; /* value for SETVAL */ 65 struct semid_ds *buf; /* buffer for IPC_STAT & IPC_SET */ 66 u_short *array; /* array for GETALL & SETALL */ 67}; 68.Ed 69.Pp 70Commands are performed as follows: 71.\" 72.\" This section based on Stevens, _Advanced Programming in the UNIX 73.\" Environment_. 74.\" 75.Bl -tag -width IPC_RMIDXXX 76.It Dv IPC_STAT 77Fetch the semaphore set's 78.Fa "struct semid_ds" , 79storing it in the memory pointed to by 80.Fa arg.buf . 81.It Dv IPC_SET 82Changes the 83.Fa sem_perm.uid , 84.Fa sem_perm.gid , 85and 86.Fa sem_perm.mode 87members of the semaphore set's 88.Fa "struct semid_ds" 89to match those of the struct pointed to by 90.Fa arg.buf . 91The calling process's effective uid must 92match either 93.Fa sem_perm.uid 94or 95.Fa sem_perm.cuid , 96or it must have superuser privileges. 97.It IPC_RMID 98Immediately removes the semaphore set from the system. 99The calling 100process's effective uid must equal the semaphore set's 101.Fa sem_perm.uid 102or 103.Fa sem_perm.cuid , 104or the process must have superuser privileges. 105.It Dv GETVAL 106Return the value of semaphore number 107.Fa semnum . 108.It Dv SETVAL 109Set the value of semaphore number 110.Fa semnum 111to 112.Fa arg.val . 113Outstanding adjust on exit values for this semaphore in any process 114are cleared. 115.It Dv GETPID 116Return the pid of the last process to perform an operation on 117semaphore number 118.Fa semnum . 119.It Dv GETNCNT 120Return the number of processes waiting for semaphore number 121.Fa semnum Ns 's 122value to become greater than its current value. 123.It Dv GETZCNT 124Return the number of processes waiting for semaphore number 125.Fa semnum Ns 's 126value to become 0. 127.It Dv GETALL 128Fetch the value of all of the semaphores in the set into the 129array pointed to by 130.Fa arg.array . 131.It Dv SETALL 132Set the values of all of the semaphores in the set to the values 133in the array pointed to by 134.Fa arg.array . 135Outstanding adjust on exit values for all semaphores in this set, 136in any process are cleared. 137.El 138.Pp 139The 140.Vt "struct semid_ds" 141is defined as follows: 142.\" 143.\" Taken straight from <sys/sem.h>. 144.\" 145.Bd -literal 146struct semid_ds { 147 struct ipc_perm sem_perm; /* operation permission struct */ 148 struct sem *sem_base; /* pointer to first semaphore in set */ 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