1.\" $NetBSD: semctl.2,v 1.4 1997/11/27 10:25:04 mikel Exp $ 2.\" 3.\" Copyright (c) 1995 Frank van der Linden 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.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed for the NetBSD Project 17.\" by Frank van der Linden 18.\" 4. The name of the author may not be used to endorse or promote products 19.\" derived from this software without specific prior written permission 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 26.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd August 17, 1995 33.Dt SEMCTL 2 34.Os NetBSD 35.Sh NAME 36.Nm semctl 37.Nd semaphore control operations 38.Sh SYNOPSIS 39.Fd #include <sys/types.h> 40.Fd #include <sys/ipc.h> 41.Fd #include <sys/sem.h> 42.Ft int 43.Fn semctl "int semid" "int semnum" "int cmd" "union semun arg" 44.Sh DESCRIPTION 45The 46.Fn semctl 47system call provides a number of control operations on the semaphore specified 48by 49.Fa semnum 50and 51.Fa semid . 52The operation to be performed is specified in 53.Fa cmd 54(see below). 55.Fa arg 56is a union of the following fields: 57.Bd -literal 58 int val; /* value for SETVAL */ 59 struct semid_ds *buf; /* buffer for IPC_{STAT,SET} */ 60 u_short *array; /* array for GETALL & SETALL */ 61.Ed 62.Pp 63The 64.Bf -literal 65semid_ds 66.Ef 67structure used in the 68.Dv IPC_SET 69and 70.Dv IPC_STAT 71commands is defined as follows in 72.Aq Pa sys/sem.h : 73.Bd -literal 74struct semid_ds { 75 struct ipc_perm sem_perm; /* operation permissions */ 76 struct sem *sem_base; /* semaphore set */ 77 u_short sem_nsems; /* number of sems in set */ 78 time_t sem_otime; /* last operation time */ 79 time_t sem_ctime; /* last change time */ 80}; 81.Ed 82.Pp 83The 84.Bf -literal 85ipc_perm 86.Ef 87structure used inside the 88.Bf -literal 89semid_ds 90.Ef 91structure is defined in 92.Aq Pa sys/ipc.h 93and looks like this: 94.Bd -literal 95struct ipc_perm { 96 ushort cuid; /* creator user id */ 97 ushort cgid; /* creator group id */ 98 ushort uid; /* user id */ 99 ushort gid; /* group id */ 100 ushort mode; /* r/w permission (see chmod(2)) */ 101 ushort seq; /* sequence # (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.Fa 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 of all the semaphores associated with 123.Fa semid . 124.It Dv SETALL 125Set the values of all the semaphores that are associated with the semaphore 126identifier 127.Fa semid 128to the corresponding values in 129.Fa 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 super-user, 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. Only the 158super-user 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. All other operations 191will make 192.Fn semctl 193return 0 if no errors occur. Otherwise -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 super-user, 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 222specifies an invalid address. 223.El 224.Sh SEE ALSO 225.Xr semget 2 , 226.Xr semop 2 227