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.\" $FreeBSD: src/lib/libc/sys/semctl.2,v 1.9.2.6 2002/03/11 08:37:47 maxim Exp $ 27.\" 28.Dd January 4, 2014 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 ".Dv IPC_RMID" 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 Dv IPC_RMID 96Immediately removes the semaphore set from the system. 97The calling process'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 . 110.It Dv GETPID 111Return the pid of the last process to perform an operation on 112semaphore number 113.Fa semnum . 114.It Dv GETNCNT 115Return the number of processes waiting for semaphore number 116.Fa semnum Ns 's 117value to become greater than its current value. 118.It Dv GETZCNT 119Return the number of processes waiting for semaphore number 120.Fa semnum Ns 's 121value to become 0. 122.It Dv GETALL 123Fetch the value of all of the semaphores in the set into the 124array pointed to by 125.Fa arg.array . 126.It Dv SETALL 127Set the values of all of the semaphores in the set to the values 128in the array pointed to by 129.Fa arg.array . 130.El 131.Pp 132The 133.Fa "struct semid_ds" 134is defined as follows: 135.Bd -literal 136.\" 137.\" Taken straight from <sys/sem.h>. 138.\" 139struct semid_ds { 140 struct ipc_perm sem_perm; /* operation permission struct */ 141 struct sem *sem_base; /* pointer to first semaphore in set */ 142 u_short sem_nsems; /* number of sems in set */ 143 time_t sem_otime; /* last operation time */ 144 long sem_pad1; /* SVABI/386 says I need this here */ 145 time_t sem_ctime; /* last change time */ 146 /* Times measured in secs since */ 147 /* 00:00:00 GMT, Jan. 1, 1970 */ 148 long sem_pad2; /* SVABI/386 says I need this here */ 149 long sem_pad3[4]; /* SVABI/386 says I need this here */ 150}; 151.Ed 152.Sh RETURN VALUES 153On success, when 154.Fa cmd 155is one of 156.Dv GETVAL , GETPID , GETNCNT 157or 158.Dv GETZCNT , 159.Fn semctl 160returns the corresponding value; otherwise, 0 is returned. 161On failure, -1 is returned, and 162.Va errno 163is set to indicate the error. 164.Sh ENVIRONMENT 165The XSI Interprocess Communication family of functions is also available 166as an implementation in userspace. 167To use it, the 168.Xr sysvipcd 8 169daemon has to be running. 170.Pp 171If the 172.Ev USR_SYSVIPC 173variable is set in a process' environment, the process and its children 174will use the userspace implementation. 175.Sh ERRORS 176.Fn Semctl 177will fail if: 178.Bl -tag -width Er 179.It Bq Er EINVAL 180No semaphore set corresponds to 181.Fa semid . 182.It Bq Er EINVAL 183.Fa semnum 184is not in the range of valid semaphores for given semaphore set. 185.It Bq Er EPERM 186The calling process's effective uid does not match the uid of 187the semaphore set's owner or creator. 188.It Bq Er EACCES 189Permission denied due to mismatch between operation and mode of 190semaphore set. 191.El 192.Sh SEE ALSO 193.Xr semget 2 , 194.Xr semop 2 195.Sh AUTHORS 196.An -nosplit 197The 198.Dx 199specific userspace implementation (see 200.Sx ENVIRONMENT ) 201was written by 202.An Larisa Grigore . 203