lib/libc/sys/semctl.2

   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$
  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
  43 The
  44 .Fn semctl
  45 system call
  46 performs the operation indicated by
  47 .Fa cmd
  48 on the semaphore set indicated by
  49 .Fa semid .
  50 A fourth argument, a
  51 .Fa "union semun arg" ,
  52 is required for certain values of
  53 .Fa cmd .
  54 For the commands that use the
  55 .Fa arg
  56 argument,
  57 .Fa "union semun"
  58 is defined as follows:
  59 .\"
  60 .\" From <sys/sem.h>:
  61 .\"
  62 .Bd -literal
  63 union 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
  70 Commands 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
  77 Fetch the semaphore set's
  78 .Fa "struct semid_ds" ,
  79 storing it in the memory pointed to by
  80 .Fa arg.buf .
  81 .It Dv IPC_SET
  82 Changes the
  83 .Fa sem_perm.uid ,
  84 .Fa sem_perm.gid ,
  85 and
  86 .Fa sem_perm.mode
  87 members of the semaphore set's
  88 .Fa "struct semid_ds"
  89 to match those of the struct pointed to by
  90 .Fa arg.buf .
  91 The calling process's effective uid must
  92 match either
  93 .Fa sem_perm.uid
  94 or
  95 .Fa sem_perm.cuid ,
  96 or it must have superuser privileges.
  97 .It IPC_RMID
  98 Immediately removes the semaphore set from the system.
  99 The calling
 100 process's effective uid must equal the semaphore set's
 101 .Fa sem_perm.uid
 102 or
 103 .Fa sem_perm.cuid ,
 104 or the process must have superuser privileges.
 105 .It Dv GETVAL
 106 Return the value of semaphore number
 107 .Fa semnum .
 108 .It Dv SETVAL
 109 Set the value of semaphore number
 110 .Fa semnum
 111 to
 112 .Fa arg.val .
 113 Outstanding adjust on exit values for this semaphore in any process
 114 are cleared.
 115 .It Dv GETPID
 116 Return the pid of the last process to perform an operation on
 117 semaphore number
 118 .Fa semnum .
 119 .It Dv GETNCNT
 120 Return the number of processes waiting for semaphore number
 121 .Fa semnum Ns 's
 122 value to become greater than its current value.
 123 .It Dv GETZCNT
 124 Return the number of processes waiting for semaphore number
 125 .Fa semnum Ns 's
 126 value to become 0.
 127 .It Dv GETALL
 128 Fetch the value of all of the semaphores in the set into the
 129 array pointed to by
 130 .Fa arg.array .
 131 .It Dv SETALL
 132 Set the values of all of the semaphores in the set to the values
 133 in the array pointed to by
 134 .Fa arg.array .
 135 Outstanding adjust on exit values for all semaphores in this set,
 136 in any process are cleared.
 137 .El
 138 .Pp
 139 The
 140 .Vt "struct semid_ds"
 141 is defined as follows:
 142 .\"
 143 .\" Taken straight from <sys/sem.h>.
 144 .\"
 145 .Bd -literal
 146 struct 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         time_t  sem_ctime;      /* last change time */
 152                                 /* Times measured in secs since */
 153                                 /* 00:00:00 GMT, Jan. 1, 1970 */
 154 };
 155 .Ed
 156 .Sh RETURN VALUES
 157 On success, when
 158 .Fa cmd
 159 is one of
 160 .Dv GETVAL , GETPID , GETNCNT
 161 or
 162 .Dv GETZCNT ,
 163 .Fn semctl
 164 returns the corresponding value; otherwise, 0 is returned.
 165 On failure, -1 is returned, and
 166 .Va errno
 167 is set to indicate the error.
 168 .Sh ERRORS
 169 The
 170 .Fn semctl
 171 system call
 172 will fail if:
 173 .Bl -tag -width Er
 174 .It Bq Er EINVAL
 175 No semaphore set corresponds to
 176 .Fa semid .
 177 .It Bq Er EINVAL
 178 The
 179 .Fa semnum
 180 argument
 181 is not in the range of valid semaphores for given semaphore set.
 182 .It Bq Er EPERM
 183 The calling process's effective uid does not match the uid of
 184 the semaphore set's owner or creator.
 185 .It Bq Er EACCES
 186 Permission denied due to mismatch between operation and mode of
 187 semaphore set.
 188 .It Bq Er ERANGE
 189 .Dv SETVAL
 190 or
 191 .Dv SETALL
 192 attempted to set a semaphore outside the allowable range
 193 .Bq 0 .. Dv SEMVMX .
 194 .El
 195 .Sh SEE ALSO
 196 .Xr semget 2 ,
 197 .Xr semop 2
 198 .Sh BUGS
 199 .Dv SETALL
 200 may update some semaphore elements before returning an error.