1.\" $OpenBSD: semctl.2,v 1.16 2014/11/15 22:19:53 guenther Exp $ 2.\" $NetBSD: semctl.2,v 1.2 1997/03/27 08:20:40 mikel Exp $ 3.\" 4.\" Copyright (c) 1995 Frank van der Linden 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed for the NetBSD Project 18.\" by Frank van der Linden 19.\" 4. The name of the author may not be used to endorse or promote products 20.\" derived from this software without specific prior written permission 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\"/ 33.Dd $Mdocdate: November 15 2014 $ 34.Dt SEMCTL 2 35.Os 36.Sh NAME 37.Nm semctl 38.Nd semaphore control operations 39.Sh SYNOPSIS 40.In sys/sem.h 41.Ft int 42.Fn semctl "int semid" "int semnum" "int cmd" "union semun arg" 43.Sh DESCRIPTION 44The 45.Fn semctl 46system call provides a number of control operations on the semaphore specified 47by 48.Fa semnum 49and 50.Fa semid . 51The operation to be performed is specified in 52.Fa cmd 53(see below). 54.Fa arg 55is a union of the following fields: 56.Bd -literal 57 int val; /* value for SETVAL */ 58 struct semid_ds *buf; /* buffer for IPC_{STAT,SET} */ 59 u_short *array; /* array for GETALL & SETALL */ 60.Ed 61.Pp 62The 63.Bf -literal 64semid_ds 65.Ef 66structure used in the 67.Dv IPC_SET 68and 69.Dv IPC_STAT 70commands is defined as follows in 71.In sys/sem.h : 72.Bd -literal 73struct semid_ds { 74 struct ipc_perm sem_perm; /* operation permissions */ 75 struct sem *sem_base; /* semaphore set */ 76 u_short sem_nsems; /* number of sems in set */ 77 time_t sem_otime; /* last operation time */ 78 time_t sem_ctime; /* last change time */ 79}; 80.Ed 81.Pp 82The 83.Bf -literal 84ipc_perm 85.Ef 86structure used inside the 87.Bf -literal 88semid_ds 89.Ef 90structure is defined in 91.In sys/ipc.h 92and looks like this: 93.Bd -literal 94struct ipc_perm { 95 uid_t cuid; /* creator user id */ 96 gid_t cgid; /* creator group id */ 97 uid_t uid; /* user id */ 98 gid_t gid; /* group id */ 99 mode_t mode; /* r/w permission (see chmod(2)) */ 100 u_short seq; /* sequence # (to generate unique msg/sem/shm id) */ 101 key_t key; /* user specified msg/sem/shm key */ 102}; 103.Ed 104.Pp 105.Fn semctl 106provides the following operations: 107.Bl -tag -width IPC_RMIDX 108.It Dv GETVAL 109Return the value of the semaphore. 110.It Dv SETVAL 111Set the value of the semaphore to 112.Va arg.val . 113.It Dv GETPID 114Return the pid of the last process that did an operation on this semaphore. 115.It Dv GETNCNT 116Return the number of processes waiting to acquire the semaphore. 117.It Dv GETZCNT 118Return the number of processes waiting for the value of the semaphore to 119reach 0. 120.It Dv GETALL 121Return the values for all the semaphores associated with 122.Fa semid . 123.It Dv SETALL 124Set the values for all the semaphores that are associated with the semaphore 125identifier 126.Fa semid 127to the corresponding values in 128.Va arg.array . 129.It Dv IPC_STAT 130Gather statistics about a semaphore and place the information in the 131.Bf -literal 132semid_ds 133.Ef 134structure pointed to by 135.Fa arg.buf 136(see above). 137.It Dv IPC_SET 138Set the value of the 139.Va sem_perm.uid , 140.Va sem_perm.gid 141and 142.Va sem_perm.mode 143fields in the structure associated with the semaphore. 144The values are taken from the corresponding fields in the structure 145pointed to by 146.Fa arg.buf . 147This operation can only be executed by the superuser, or a process that 148has an effective user ID equal to either 149.Va sem_perm.cuid 150or 151.Va sem_perm.uid 152in the data structure associated with the message queue. 153.It Dv IPC_RMID 154Remove the semaphores associated with 155.Fa semid 156from the system and destroy the data structures associated with it. 157Only the superuser or a process with an effective UID equal to the 158.Va sem_perm.cuid 159or 160.Va sem_perm.uid 161values in the data structure associated with the semaphore can do this. 162.El 163.Pp 164The permission to read or change a message queue (see 165.Xr semop 2 ) 166is determined by the 167.Va sem_perm.mode 168field in the same way as is 169done with files (see 170.Xr chmod 2 ) , 171but the effective UID can match either the 172.Va sem_perm.cuid 173field or the 174.Va sem_perm.uid 175field, and the 176effective GID can match either 177.Va sem_perm.cgid 178or 179.Va sem_perm.gid . 180.Sh RETURN VALUES 181For the 182.Dv GETVAL , 183.Dv GETPID , 184.Dv GETNCNT , 185and 186.Dv GETZCNT 187operations, 188.Fn semctl 189returns one of the values described above if successful. 190All other operations will make 191.Fn semctl 192return 0 if no errors occur. 193Otherwise \-1 is returned and 194.Va errno 195set to reflect the error. 196.Sh ERRORS 197.Fn semctl 198will fail if: 199.Bl -tag -width Er 200.It Bq Er EPERM 201.Fa cmd 202is equal to 203.Dv IPC_SET 204or 205.Dv IPC_RMID 206and the caller is not the superuser, nor does 207the effective UID match either the 208.Va sem_perm.uid 209or 210.Va sem_perm.cuid 211fields of the data structure associated with the message queue. 212.It Bq Er EACCES 213The caller has no operation permission for this semaphore. 214.It Bq Er EINVAL 215.Fa semid 216is not a valid message semaphore identifier. 217.Pp 218.Va cmd 219is not a valid command. 220.It Bq Er EFAULT 221.Fa arg.buf 222or 223.Fa arg.array 224specify an invalid address. 225.It Bq Er ERANGE 226.Fa cmd 227is equal to 228.Dv SETVAL 229or 230.Dv SETALL 231and 232.Va arg.val 233or the values in 234.Va arg.array 235are greater than the system-imposed limit. 236.El 237.Sh SEE ALSO 238.Xr semget 2 , 239.Xr semop 2 240