1.\" $NetBSD: semctl.2,v 1.1 1995/10/16 23:49:26 jtc 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 63The 64.Bf -literal 65semid_ds 66.Ef 67structure used in the IPC_SET and IPC_STAT commands is defined 68as follows in 69.Aq Pa sys/sem.h : 70.Bd -literal 71struct semid_ds { 72 struct ipc_perm sem_perm; /* operation permissions */ 73 struct sem *sem_base; /* semaphore set */ 74 u_short sem_nsems; /* number of sems in set */ 75 time_t sem_otime; /* last operation time */ 76 time_t sem_ctime; /* last change time */ 77}; 78.Ed 79 80The 81.Bf -literal 82ipc_perm 83.Ef 84structure used inside the 85.Bf -literal 86semid_ds 87.Ef 88structure is defined in 89.Aq Pa sys/ipc.h 90and looks like this: 91.Bd -literal 92struct ipc_perm { 93 ushort cuid; /* creator user id */ 94 ushort cgid; /* creator group id */ 95 ushort uid; /* user id */ 96 ushort gid; /* group id */ 97 ushort mode; /* r/w permission (see chmod(2)) */ 98 ushort seq; /* sequence # (to generate unique msg/sem/shm id) */ 99 key_t key; /* user specified msg/sem/shm key */ 100}; 101.Ed 102 103.Fn semctl 104provides the following operations: 105.Bl -tag -width IPC_RMIDX 106.It Dv GETVAL 107Return the value of the semaphore. 108.It Dv SETVAL 109Set the value of the semaphore to 110.Va arg.val . 111.It Dv GETPID 112Return the pid of the last process that did an operation on this semaphore. 113.It Dv GETNCNT 114Return the number of processes waiting to acquire the semaphore. 115.It Dv GETZCNT 116Return the number of processes waiting for the value of the semaphore to 117reach 0. 118.It Dv GETALL 119Return the values for all the semaphores associated with 120.Fa semid . 121.It Dv SETALL 122Set the values for all the semaphores that are associated with the semaphore 123identifier 124.Fa semid 125to the corresponding values in 126.Va arg.array . 127.It Dv IPC_STAT 128Gather statistics about a semaphore and place the information in the 129.Bf -literal 130semid_ds 131.Ef 132structure pointed to by 133.Fa arg.buf 134(see above). 135.It Dv IPC_SET 136Set the value of the 137.Va sem_perm.uid , 138.Va sem_perm.gid 139and 140.Va sem_perm.mode 141fields in the structure associated with the semaphore. 142The values are taken from the corresponding fields in the structure 143pointed to by 144.Fa arg.buf . 145This operation can only be executed by the super-user, or a process that 146has an effective user id equal to either 147.Va sem_perm.cuid 148or 149.Va sem_perm.uid 150in the data structure associated with the message queue. 151.It Dv IPC_RMID 152Remove the semaphores associated with 153.Fa semid 154from the system and destroy the data structures associated with it. Only the 155super-user or a process with an effective uid equal to the 156.Va sem_perm.cuid 157or 158.Va sem_perm.uid 159values in the data structure associated with the semaphore can do this. 160.El 161 162The permission to read or change a message queue (see 163.Xr semop 2 ) 164is determined by the 165.Va sem_perm.mode 166field in the same way as is 167done with files (see 168.Xr chmod 2 ), 169but the effective uid can match either the 170.Va sem_perm.cuid 171field or the 172.Va sem_perm.uid 173field, and the 174effective gid can match either 175.Va sem_perm.cgid 176or 177.Va sem_perm.gid . 178.Sh RETURN VALUES 179For the GETVAL, GETPID, GETNCNT and GETZCNT operations, 180.Fn semctl 181returns one of the values described above if successful. All other operations 182will make 183.Fn semctl 184return 0 if no errors occur. Otherwise -1 is returned and 185.Va errno 186set to reflect the error. 187.Sh ERRORS 188.Fn semctl 189will fail if: 190.Bl -tag -width Er 191.It Bq Er EPERM 192.Fa cmd 193is equal to IPC_SET or IPC_RMID and the caller is not the super-user, nor does 194the effective uid match either the 195.Va sem_perm.uid 196or 197.Va sem_perm.cuid 198fields of the data structure associated with the message queue. 199.It Bq Er EACCESS 200The caller has no operation permission for this semaphore. 201.It Bq Er EINVAL 202.Fa semid 203is not a valid message semaphore identifier. 204 205.Va cmd 206is not a valid command. 207.It Bq Er EFAULT 208.Fa arg.buf 209specifies an invalid address. 210.El 211.Sh SEE ALSO 212.Xr semop 2 213.Xr semget 2 214