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 43.Fn Semctl 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 54parameter, 55.Fa "union semun" 56is defined as follows: 57.Bd -literal 58.\" 59.\" From <sys/sem.h>: 60.\" 61union semun { 62 int val; /* value for SETVAL */ 63 struct semid_ds *buf; /* buffer for IPC_STAT & IPC_SET */ 64 u_short *array; /* array for GETALL & SETALL */ 65}; 66.Ed 67.Pp 68Commands are performed as follows: 69.\" 70.\" This section based on Stevens, _Advanced Programming in the UNIX 71.\" Environment_. 72.\" 73.Bl -tag -width IPC_RMIDXXX 74.It Dv IPC_STAT 75Fetch the semaphore set's 76.Fa "struct semid_ds" , 77storing it in the memory pointed to by 78.Fa arg.buf . 79.It Dv IPC_SET 80Changes the 81.Fa sem_perm.uid , 82.Fa sem_perm.gid , 83and 84.Fa sem_perm.mode 85members of the semaphore set's 86.Fa "struct semid_ds" 87to match those of the struct pointed to by 88.Fa arg.buf . 89The calling process's effective uid must 90match either 91.Fa sem_perm.uid 92or 93.Fa sem_perm.cuid , 94or it must have superuser privileges. 95.It IPC_RMID 96Immediately removes the semaphore set from the system. The calling 97process's effective uid must equal the semaphore set's 98.Fa sem_perm.uid 99or 100.Fa sem_perm.cuid , 101or the process must have superuser privileges. 102.It Dv GETVAL 103Return the value of semaphore number 104.Fa semnum . 105.It Dv SETVAL 106Set the value of semaphore number 107.Fa semnum 108to 109.Fa arg.val . 110Outstanding adjust on exit values for this semaphore in any process 111are cleared. 112.It Dv GETPID 113Return the pid of the last process to perform an operation on 114semaphore number 115.Fa semnum . 116.It Dv GETNCNT 117Return the number of processes waiting for semaphore number 118.Fa semnum Ns 's 119value to become greater than its current value. 120.It Dv GETZCNT 121Return the number of processes waiting for semaphore number 122.Fa semnum Ns 's 123value to become 0. 124.It Dv GETALL 125Fetch the value of all of the semaphores in the set into the 126array pointed to by 127.Fa arg.array . 128.It Dv SETALL 129Set the values of all of the semaphores in the set to the values 130in the array pointed to by 131.Fa arg.array . 132Outstanding adjust on exit values for all semaphores in this set, 133in any process are cleared. 134.El 135.Pp 136The 137.Fa "struct semid_ds" 138is defined as follows: 139.Bd -literal 140.\" 141.\" Taken straight from <sys/sem.h>. 142.\" 143struct semid_ds { 144 struct ipc_perm sem_perm; /* operation permission struct */ 145 struct sem *sem_base; /* pointer to first semaphore in set */ 146 u_short sem_nsems; /* number of sems in set */ 147 time_t sem_otime; /* last operation time */ 148 long sem_pad1; /* SVABI/386 says I need this here */ 149 time_t sem_ctime; /* last change time */ 150 /* Times measured in secs since */ 151 /* 00:00:00 GMT, Jan. 1, 1970 */ 152 long sem_pad2; /* SVABI/386 says I need this here */ 153 long sem_pad3[4]; /* SVABI/386 says I need this here */ 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 169.Fn Semctl 170will fail if: 171.Bl -tag -width Er 172.It Bq Er EINVAL 173No semaphore set corresponds to 174.Fa semid . 175.It Bq Er EINVAL 176.Fa semnum 177is not in the range of valid semaphores for given semaphore set. 178.It Bq Er EPERM 179The calling process's effective uid does not match the uid of 180the semaphore set's owner or creator. 181.It Bq Er EACCES 182Permission denied due to mismatch between operation and mode of 183semaphore set. 184.It Bq Er ERANGE 185.Dv SETVAL 186or 187.Dv SETALL 188attempted to set a semaphore outside the allowable range 189.Bq 0 .. Dv SEMVMX . 190.El 191.Sh SEE ALSO 192.Xr semget 2 , 193.Xr semop 2 194.Sh BUGS 195.Dv SETALL 196may update some semaphore elements before returning an error. 197