1.\" $OpenBSD: semctl.2,v 1.18 2021/11/21 23:44:55 jan 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 21 2021 $ 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 # */ 101 /* (to generate unique msg/sem/shm id) */ 102 key_t key; /* user specified msg/sem/shm key */ 103}; 104.Ed 105.Pp 106.Fn semctl 107provides the following operations: 108.Bl -tag -width IPC_RMIDX 109.It Dv GETVAL 110Return the value of the semaphore. 111.It Dv SETVAL 112Set the value of the semaphore to 113.Va arg.val . 114.It Dv GETPID 115Return the pid of the last process that did an operation on this semaphore. 116.It Dv GETNCNT 117Return the number of processes waiting to acquire the semaphore. 118.It Dv GETZCNT 119Return the number of processes waiting for the value of the semaphore to 120reach 0. 121.It Dv GETALL 122Return the values for all the semaphores associated with 123.Fa semid . 124.It Dv SETALL 125Set the values for all the semaphores that are associated with the semaphore 126identifier 127.Fa semid 128to the corresponding values in 129.Va arg.array . 130.It Dv IPC_STAT 131Gather statistics about a semaphore and place the information in the 132.Bf -literal 133semid_ds 134.Ef 135structure pointed to by 136.Fa arg.buf 137(see above). 138.It Dv IPC_SET 139Set the value of the 140.Va sem_perm.uid , 141.Va sem_perm.gid 142and 143.Va sem_perm.mode 144fields in the structure associated with the semaphore. 145The values are taken from the corresponding fields in the structure 146pointed to by 147.Fa arg.buf . 148This operation can only be executed by the superuser, or a process that 149has an effective user ID equal to either 150.Va sem_perm.cuid 151or 152.Va sem_perm.uid 153in the data structure associated with the message queue. 154.It Dv IPC_RMID 155Remove the semaphores associated with 156.Fa semid 157from the system and destroy the data structures associated with it. 158Only the superuser or a process with an effective UID equal to the 159.Va sem_perm.cuid 160or 161.Va sem_perm.uid 162values in the data structure associated with the semaphore can do this. 163.El 164.Pp 165The permission to read or change a message queue (see 166.Xr semop 2 ) 167is determined by the 168.Va sem_perm.mode 169field in the same way as is 170done with files (see 171.Xr chmod 2 ) , 172but the effective UID can match either the 173.Va sem_perm.cuid 174field or the 175.Va sem_perm.uid 176field, and the 177effective GID can match either 178.Va sem_perm.cgid 179or 180.Va sem_perm.gid . 181.Sh RETURN VALUES 182For the 183.Dv GETVAL , 184.Dv GETPID , 185.Dv GETNCNT , 186and 187.Dv GETZCNT 188operations, 189.Fn semctl 190returns one of the values described above if successful. 191All other operations will make 192.Fn semctl 193return 0 if no errors occur. 194Otherwise \-1 is returned and 195.Va errno 196set to reflect the error. 197.Sh ERRORS 198.Fn semctl 199will fail if: 200.Bl -tag -width Er 201.It Bq Er EPERM 202.Fa cmd 203is equal to 204.Dv IPC_SET 205or 206.Dv IPC_RMID 207and the caller is not the superuser, nor does 208the effective UID match either the 209.Va sem_perm.uid 210or 211.Va sem_perm.cuid 212fields of the data structure associated with the message queue. 213.It Bq Er EACCES 214The caller has no operation permission for this semaphore. 215.It Bq Er EINVAL 216.Fa semid 217is not a valid message semaphore identifier. 218.Pp 219.Va cmd 220is not a valid command. 221.It Bq Er EFAULT 222.Fa arg.buf 223or 224.Fa arg.array 225specify an invalid address. 226.It Bq Er ERANGE 227.Fa cmd 228is equal to 229.Dv SETVAL 230or 231.Dv SETALL 232and 233.Va arg.val 234or the values in 235.Va arg.array 236are greater than the system-imposed limit. 237.El 238.Sh SEE ALSO 239.Xr ipcrm 1 , 240.Xr ipcs 1 , 241.Xr semget 2 , 242.Xr semop 2 243