1.\" 2.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> 3.\" 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.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\"
| 1.\" 2.\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com> 3.\" 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.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\"
|
26.\" $FreeBSD: head/lib/libc/sys/semctl.2 108087 2002-12-19 09:40:28Z ru $
| 26.\" $FreeBSD: head/lib/libc/sys/semctl.2 131504 2004-07-02 23:52:20Z ru $
|
27.\" 28.Dd September 12, 1995 29.Dt SEMCTL 2 30.Os 31.Sh NAME 32.Nm semctl 33.Nd control operations on a semaphore set 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In sys/types.h 38.In sys/ipc.h 39.In sys/sem.h 40.Ft int 41.Fn semctl "int semid" "int semnum" "int cmd" ... 42.Sh DESCRIPTION 43The 44.Fn semctl 45system call 46performs the operation indicated by 47.Fa cmd 48on the semaphore set indicated by 49.Fa semid . 50A fourth argument, a 51.Fa "union semun arg" , 52is required for certain values of 53.Fa cmd . 54For the commands that use the 55.Fa arg 56argument, 57.Fa "union semun" 58is defined as follows: 59.Bd -literal 60.\" 61.\" From <sys/sem.h>: 62.\" 63union semun { 64 int val; /* value for SETVAL */ 65 struct semid_ds *buf; /* buffer for IPC_STAT & IPC_SET */ 66 u_short *array; /* array for GETALL & SETALL */ 67}; 68.Ed 69.Pp 70Commands are performed as follows: 71.\" 72.\" This section based on Stevens, _Advanced Programming in the UNIX 73.\" Environment_. 74.\" 75.Bl -tag -width IPC_RMIDXXX 76.It Dv IPC_STAT 77Fetch the semaphore set's 78.Fa "struct semid_ds" , 79storing it in the memory pointed to by 80.Fa arg.buf . 81.It Dv IPC_SET 82Changes the 83.Fa sem_perm.uid , 84.Fa sem_perm.gid , 85and 86.Fa sem_perm.mode 87members of the semaphore set's 88.Fa "struct semid_ds" 89to match those of the struct pointed to by 90.Fa arg.buf . 91The calling process's effective uid must 92match either 93.Fa sem_perm.uid 94or 95.Fa sem_perm.cuid , 96or it must have superuser privileges. 97.It IPC_RMID
| 27.\" 28.Dd September 12, 1995 29.Dt SEMCTL 2 30.Os 31.Sh NAME 32.Nm semctl 33.Nd control operations on a semaphore set 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In sys/types.h 38.In sys/ipc.h 39.In sys/sem.h 40.Ft int 41.Fn semctl "int semid" "int semnum" "int cmd" ... 42.Sh DESCRIPTION 43The 44.Fn semctl 45system call 46performs the operation indicated by 47.Fa cmd 48on the semaphore set indicated by 49.Fa semid . 50A fourth argument, a 51.Fa "union semun arg" , 52is required for certain values of 53.Fa cmd . 54For the commands that use the 55.Fa arg 56argument, 57.Fa "union semun" 58is defined as follows: 59.Bd -literal 60.\" 61.\" From <sys/sem.h>: 62.\" 63union semun { 64 int val; /* value for SETVAL */ 65 struct semid_ds *buf; /* buffer for IPC_STAT & IPC_SET */ 66 u_short *array; /* array for GETALL & SETALL */ 67}; 68.Ed 69.Pp 70Commands are performed as follows: 71.\" 72.\" This section based on Stevens, _Advanced Programming in the UNIX 73.\" Environment_. 74.\" 75.Bl -tag -width IPC_RMIDXXX 76.It Dv IPC_STAT 77Fetch the semaphore set's 78.Fa "struct semid_ds" , 79storing it in the memory pointed to by 80.Fa arg.buf . 81.It Dv IPC_SET 82Changes the 83.Fa sem_perm.uid , 84.Fa sem_perm.gid , 85and 86.Fa sem_perm.mode 87members of the semaphore set's 88.Fa "struct semid_ds" 89to match those of the struct pointed to by 90.Fa arg.buf . 91The calling process's effective uid must 92match either 93.Fa sem_perm.uid 94or 95.Fa sem_perm.cuid , 96or it must have superuser privileges. 97.It IPC_RMID
|
98Immediately removes the semaphore set from the system. The calling
| 98Immediately removes the semaphore set from the system. 99The calling
|
99process's effective uid must equal the semaphore set's 100.Fa sem_perm.uid 101or 102.Fa sem_perm.cuid , 103or the process must have superuser privileges. 104.It Dv GETVAL 105Return the value of semaphore number 106.Fa semnum . 107.It Dv SETVAL 108Set the value of semaphore number 109.Fa semnum 110to 111.Fa arg.val . 112Outstanding adjust on exit values for this semaphore in any process 113are cleared. 114.It Dv GETPID 115Return the pid of the last process to perform an operation on 116semaphore number 117.Fa semnum . 118.It Dv GETNCNT 119Return the number of processes waiting for semaphore number 120.Fa semnum Ns 's 121value to become greater than its current value. 122.It Dv GETZCNT 123Return the number of processes waiting for semaphore number 124.Fa semnum Ns 's 125value to become 0. 126.It Dv GETALL 127Fetch the value of all of the semaphores in the set into the 128array pointed to by 129.Fa arg.array . 130.It Dv SETALL 131Set the values of all of the semaphores in the set to the values 132in the array pointed to by 133.Fa arg.array . 134Outstanding adjust on exit values for all semaphores in this set, 135in any process are cleared. 136.El 137.Pp 138The 139.Vt "struct semid_ds" 140is defined as follows: 141.Bd -literal 142.\" 143.\" Taken straight from <sys/sem.h>. 144.\" 145struct semid_ds { 146 struct ipc_perm sem_perm; /* operation permission struct */ 147 struct sem *sem_base; /* pointer to first semaphore in set */ 148 u_short sem_nsems; /* number of sems in set */ 149 time_t sem_otime; /* last operation time */ 150 long sem_pad1; /* SVABI/386 says I need this here */ 151 time_t sem_ctime; /* last change time */ 152 /* Times measured in secs since */ 153 /* 00:00:00 GMT, Jan. 1, 1970 */ 154 long sem_pad2; /* SVABI/386 says I need this here */ 155 long sem_pad3[4]; /* SVABI/386 says I need this here */ 156}; 157.Ed 158.Sh RETURN VALUES 159On success, when 160.Fa cmd 161is one of 162.Dv GETVAL , GETPID , GETNCNT 163or 164.Dv GETZCNT , 165.Fn semctl 166returns the corresponding value; otherwise, 0 is returned. 167On failure, -1 is returned, and 168.Va errno 169is set to indicate the error. 170.Sh ERRORS 171The 172.Fn semctl 173system call 174will fail if: 175.Bl -tag -width Er 176.It Bq Er EINVAL 177No semaphore set corresponds to 178.Fa semid . 179.It Bq Er EINVAL 180The 181.Fa semnum 182argument 183is not in the range of valid semaphores for given semaphore set. 184.It Bq Er EPERM 185The calling process's effective uid does not match the uid of 186the semaphore set's owner or creator. 187.It Bq Er EACCES 188Permission denied due to mismatch between operation and mode of 189semaphore set. 190.It Bq Er ERANGE 191.Dv SETVAL 192or 193.Dv SETALL 194attempted to set a semaphore outside the allowable range 195.Bq 0 .. Dv SEMVMX . 196.El 197.Sh SEE ALSO 198.Xr semget 2 , 199.Xr semop 2 200.Sh BUGS 201.Dv SETALL 202may update some semaphore elements before returning an error.
| 100process's effective uid must equal the semaphore set's 101.Fa sem_perm.uid 102or 103.Fa sem_perm.cuid , 104or the process must have superuser privileges. 105.It Dv GETVAL 106Return the value of semaphore number 107.Fa semnum . 108.It Dv SETVAL 109Set the value of semaphore number 110.Fa semnum 111to 112.Fa arg.val . 113Outstanding adjust on exit values for this semaphore in any process 114are cleared. 115.It Dv GETPID 116Return the pid of the last process to perform an operation on 117semaphore number 118.Fa semnum . 119.It Dv GETNCNT 120Return the number of processes waiting for semaphore number 121.Fa semnum Ns 's 122value to become greater than its current value. 123.It Dv GETZCNT 124Return the number of processes waiting for semaphore number 125.Fa semnum Ns 's 126value to become 0. 127.It Dv GETALL 128Fetch the value of all of the semaphores in the set into the 129array pointed to by 130.Fa arg.array . 131.It Dv SETALL 132Set the values of all of the semaphores in the set to the values 133in the array pointed to by 134.Fa arg.array . 135Outstanding adjust on exit values for all semaphores in this set, 136in any process are cleared. 137.El 138.Pp 139The 140.Vt "struct semid_ds" 141is defined as follows: 142.Bd -literal 143.\" 144.\" Taken straight from <sys/sem.h>. 145.\" 146struct semid_ds { 147 struct ipc_perm sem_perm; /* operation permission struct */ 148 struct sem *sem_base; /* pointer to first semaphore in set */ 149 u_short sem_nsems; /* number of sems in set */ 150 time_t sem_otime; /* last operation time */ 151 long sem_pad1; /* SVABI/386 says I need this here */ 152 time_t sem_ctime; /* last change time */ 153 /* Times measured in secs since */ 154 /* 00:00:00 GMT, Jan. 1, 1970 */ 155 long sem_pad2; /* SVABI/386 says I need this here */ 156 long sem_pad3[4]; /* SVABI/386 says I need this here */ 157}; 158.Ed 159.Sh RETURN VALUES 160On success, when 161.Fa cmd 162is one of 163.Dv GETVAL , GETPID , GETNCNT 164or 165.Dv GETZCNT , 166.Fn semctl 167returns the corresponding value; otherwise, 0 is returned. 168On failure, -1 is returned, and 169.Va errno 170is set to indicate the error. 171.Sh ERRORS 172The 173.Fn semctl 174system call 175will fail if: 176.Bl -tag -width Er 177.It Bq Er EINVAL 178No semaphore set corresponds to 179.Fa semid . 180.It Bq Er EINVAL 181The 182.Fa semnum 183argument 184is not in the range of valid semaphores for given semaphore set. 185.It Bq Er EPERM 186The calling process's effective uid does not match the uid of 187the semaphore set's owner or creator. 188.It Bq Er EACCES 189Permission denied due to mismatch between operation and mode of 190semaphore set. 191.It Bq Er ERANGE 192.Dv SETVAL 193or 194.Dv SETALL 195attempted to set a semaphore outside the allowable range 196.Bq 0 .. Dv SEMVMX . 197.El 198.Sh SEE ALSO 199.Xr semget 2 , 200.Xr semop 2 201.Sh BUGS 202.Dv SETALL 203may update some semaphore elements before returning an error.
|