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 .Dd July 9, 2020
  27 .Dt SEMCTL 2
  28 .Os
  29 .Sh NAME
  30 .Nm semctl
  31 .Nd control operations on a semaphore set
  32 .Sh LIBRARY
  33 .Lb libc
  34 .Sh SYNOPSIS
  35 .In sys/types.h
  36 .In sys/ipc.h
  37 .In sys/sem.h
  38 .Ft int
  39 .Fn semctl "int semid" "int semnum" "int cmd" ...
  40 .Sh DESCRIPTION
  41 The
  42 .Fn semctl
  43 system call
  44 performs the operation indicated by
  45 .Fa cmd
  46 on the semaphore set indicated by
  47 .Fa semid .
  48 A fourth argument, a
  49 .Fa "union semun arg" ,
  50 is required for certain values of
  51 .Fa cmd .
  52 For the commands that use the
  53 .Fa arg
  54 argument,
  55 .Fa "union semun"
  56 must be defined as follows:
  57 .Bd -literal
  58 union semun {
  59         int     val;            /* value for SETVAL */
  60         struct  semid_ds *buf;  /* buffer for IPC_STAT & IPC_SET */
  61         u_short *array;         /* array for GETALL & SETALL */
  62 };
  63 .Ed
  64 Non-portable software may define
  65 .Dv _WANT_SEMUN
  66 before including
  67 .Pa sys/sem.h
  68 to use the system definition of
  69 .Fa "union semun" .
  70 .Pp
  71 Commands are performed as follows:
  72 .\"
  73 .\" This section based on Stevens, _Advanced Programming in the UNIX
  74 .\" Environment_.
  75 .\"
  76 .Bl -tag -width IPC_RMIDXXX
  77 .It Dv IPC_STAT
  78 Fetch the semaphore set's
  79 .Fa "struct semid_ds" ,
  80 storing it in the memory pointed to by
  81 .Fa arg.buf .
  82 .It Dv IPC_SET
  83 Changes the
  84 .Fa sem_perm.uid ,
  85 .Fa sem_perm.gid ,
  86 and
  87 .Fa sem_perm.mode
  88 members of the semaphore set's
  89 .Fa "struct semid_ds"
  90 to match those of the struct pointed to by
  91 .Fa arg.buf .
  92 The calling process's effective uid must
  93 match either
  94 .Fa sem_perm.uid
  95 or
  96 .Fa sem_perm.cuid ,
  97 or it must have superuser privileges.
  98 .It IPC_RMID
  99 Immediately removes the semaphore set from the system.
 100 The calling
 101 process's effective uid must equal the semaphore set's
 102 .Fa sem_perm.uid
 103 or
 104 .Fa sem_perm.cuid ,
 105 or the process must have superuser privileges.
 106 .It Dv GETVAL
 107 Return the value of semaphore number
 108 .Fa semnum .
 109 .It Dv SETVAL
 110 Set the value of semaphore number
 111 .Fa semnum
 112 to
 113 .Fa arg.val .
 114 Outstanding adjust on exit values for this semaphore in any process
 115 are cleared.
 116 .It Dv GETPID
 117 Return the pid of the last process to perform an operation on
 118 semaphore number
 119 .Fa semnum .
 120 .It Dv GETNCNT
 121 Return the number of processes waiting for semaphore number
 122 .Fa semnum Ns 's
 123 value to become greater than its current value.
 124 .It Dv GETZCNT
 125 Return the number of processes waiting for semaphore number
 126 .Fa semnum Ns 's
 127 value to become 0.
 128 .It Dv GETALL
 129 Fetch the value of all of the semaphores in the set into the
 130 array pointed to by
 131 .Fa arg.array .
 132 .It Dv SETALL
 133 Set the values of all of the semaphores in the set to the values
 134 in the array pointed to by
 135 .Fa arg.array .
 136 Outstanding adjust on exit values for all semaphores in this set,
 137 in any process are cleared.
 138 .El
 139 .Pp
 140 The
 141 .Vt "struct semid_ds"
 142 is defined as follows:
 143 .\"
 144 .\" Taken straight from <sys/sem.h>.
 145 .\"
 146 .Bd -literal
 147 struct semid_ds {
 148         struct  ipc_perm sem_perm;      /* operation permission struct */
 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.