1.\" $OpenBSD: semctl.2,v 1.13 2007/05/31 19:19:33 jmc 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: May 31 2007 $ 34.Dt SEMCTL 2 35.Os 36.Sh NAME 37.Nm semctl 38.Nd semaphore control operations 39.Sh SYNOPSIS 40.Fd #include <sys/types.h> 41.Fd #include <sys/ipc.h> 42.Fd #include <sys/sem.h> 43.Ft int 44.Fn semctl "int semid" "int semnum" "int cmd" "union semun arg" 45.Sh DESCRIPTION 46The 47.Fn semctl 48system call provides a number of control operations on the semaphore specified 49by 50.Fa semnum 51and 52.Fa semid . 53The operation to be performed is specified in 54.Fa cmd 55(see below). 56.Fa arg 57is a union of the following fields: 58.Bd -literal 59 int val; /* value for SETVAL */ 60 struct semid_ds *buf; /* buffer for IPC_{STAT,SET} */ 61 u_short *array; /* array for GETALL & SETALL */ 62.Ed 63.Pp 64The 65.Bf -literal 66semid_ds 67.Ef 68structure used in the 69.Dv IPC_SET 70and 71.Dv IPC_STAT 72commands is defined as follows in 73.Aq Pa sys/sem.h : 74.Bd -literal 75struct semid_ds { 76 struct ipc_perm sem_perm; /* operation permissions */ 77 struct sem *sem_base; /* semaphore set */ 78 u_short sem_nsems; /* number of sems in set */ 79 time_t sem_otime; /* last operation time */ 80 time_t sem_ctime; /* last change time */ 81}; 82.Ed 83.Pp 84The 85.Bf -literal 86ipc_perm 87.Ef 88structure used inside the 89.Bf -literal 90semid_ds 91.Ef 92structure is defined in 93.Aq Pa sys/ipc.h 94and looks like this: 95.Bd -literal 96struct ipc_perm { 97 uid_t cuid; /* creator user id */ 98 gid_t cgid; /* creator group id */ 99 uid_t uid; /* user id */ 100 gid_t gid; /* group id */ 101 mode_t mode; /* r/w permission (see chmod(2)) */ 102 u_short seq; /* sequence # (to generate unique msg/sem/shm id) */ 103 key_t key; /* user specified msg/sem/shm key */ 104}; 105.Ed 106.Pp 107.Fn semctl 108provides the following operations: 109.Bl -tag -width IPC_RMIDX 110.It Dv GETVAL 111Return the value of the semaphore. 112.It Dv SETVAL 113Set the value of the semaphore to 114.Va arg.val . 115.It Dv GETPID 116Return the pid of the last process that did an operation on this semaphore. 117.It Dv GETNCNT 118Return the number of processes waiting to acquire the semaphore. 119.It Dv GETZCNT 120Return the number of processes waiting for the value of the semaphore to 121reach 0. 122.It Dv GETALL 123Return the values for all the semaphores associated with 124.Fa semid . 125.It Dv SETALL 126Set the values for all the semaphores that are associated with the semaphore 127identifier 128.Fa semid 129to the corresponding values in 130.Va arg.array . 131.It Dv IPC_STAT 132Gather statistics about a semaphore and place the information in the 133.Bf -literal 134semid_ds 135.Ef 136structure pointed to by 137.Fa arg.buf 138(see above). 139.It Dv IPC_SET 140Set the value of the 141.Va sem_perm.uid , 142.Va sem_perm.gid 143and 144.Va sem_perm.mode 145fields in the structure associated with the semaphore. 146The values are taken from the corresponding fields in the structure 147pointed to by 148.Fa arg.buf . 149This operation can only be executed by the superuser, or a process that 150has an effective user ID equal to either 151.Va sem_perm.cuid 152or 153.Va sem_perm.uid 154in the data structure associated with the message queue. 155.It Dv IPC_RMID 156Remove the semaphores associated with 157.Fa semid 158from the system and destroy the data structures associated with it. 159Only the superuser or a process with an effective UID equal to the 160.Va sem_perm.cuid 161or 162.Va sem_perm.uid 163values in the data structure associated with the semaphore can do this. 164.El 165.Pp 166The permission to read or change a message queue (see 167.Xr semop 2 ) 168is determined by the 169.Va sem_perm.mode 170field in the same way as is 171done with files (see 172.Xr chmod 2 ) , 173but the effective UID can match either the 174.Va sem_perm.cuid 175field or the 176.Va sem_perm.uid 177field, and the 178effective GID can match either 179.Va sem_perm.cgid 180or 181.Va sem_perm.gid . 182.Sh RETURN VALUES 183For the 184.Dv GETVAL , 185.Dv GETPID , 186.Dv GETNCNT , 187and 188.Dv GETZCNT 189operations, 190.Fn semctl 191returns one of the values described above if successful. 192All other operations will make 193.Fn semctl 194return 0 if no errors occur. 195Otherwise \-1 is returned and 196.Va errno 197set to reflect the error. 198.Sh ERRORS 199.Fn semctl 200will fail if: 201.Bl -tag -width Er 202.It Bq Er EPERM 203.Fa cmd 204is equal to 205.Dv IPC_SET 206or 207.Dv IPC_RMID 208and the caller is not the superuser, nor does 209the effective UID match either the 210.Va sem_perm.uid 211or 212.Va sem_perm.cuid 213fields of the data structure associated with the message queue. 214.It Bq Er EACCES 215The caller has no operation permission for this semaphore. 216.It Bq Er EINVAL 217.Fa semid 218is not a valid message semaphore identifier. 219.Pp 220.Va cmd 221is not a valid command. 222.It Bq Er EFAULT 223.Fa arg.buf 224specifies an invalid address. 225.El 226.Sh SEE ALSO 227.Xr semget 2 , 228.Xr semop 2 229