bsd/man/man2/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: src/lib/libc/sys/semctl.2,v 1.18 2002/12/19 09:40:25 ru Exp $
  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 SYNOPSIS
  35 .In sys/sem.h
  36 .Ft int
  37 .Fo semctl
  38 .Fa "int semid"
  39 .Fa "int semnum"
  40 .Fa "int cmd"
  41 .Fa ...
  42 .Fc
  43 .Sh DESCRIPTION
  44 The
  45 .Fn semctl
  46 system call
  47 performs the operation indicated by
  48 .Fa cmd
  49 on the semaphore set indicated by
  50 .Fa semid .
  51 A fourth argument, a
  52 .Fa "union semun arg" ,
  53 is required for certain values of
  54 .Fa cmd .
  55 For the commands that use the
  56 .Fa arg
  57 argument,
  58 .Fa "union semun"
  59 is defined as follows:
  60 .Bd -literal
  61 .\"
  62 .\" From <sys/sem.h>:
  63 .\"
  64 union semun {
  65         int     val;            /* value for SETVAL */
  66         struct  semid_ds *buf;  /* buffer for IPC_STAT & IPC_SET */
  67         u_short *array;         /* array for GETALL & SETALL */
  68 };
  69 .Ed
  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.  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 .Bd -literal
 143 .\"
 144 .\" Taken straight from <sys/sem.h>.
 145 .\"
 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         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
 160 On success, when
 161 .Fa cmd
 162 is one of
 163 .Dv GETVAL , GETPID , GETNCNT
 164 or
 165 .Dv GETZCNT ,
 166 .Fn semctl
 167 returns the corresponding value; otherwise, 0 is returned.
 168 On failure, -1 is returned, and
 169 .Va errno
 170 is set to indicate the error.
 171 .Sh ERRORS
 172 The
 173 .Fn semctl
 174 system call
 175 will fail if:
 176 .Bl -tag -width Er
 177 .\" ===========
 178 .It Bq Er EACCES
 179 Permission denied due to mismatch between operation and mode of
 180 semaphore set.
 181 .\" ===========
 182 .It Bq Er EINVAL
 183 No semaphore set corresponds to
 184 .Fa semid .
 185 .\" ===========
 186 .It Bq Er EINVAL
 187 The
 188 .Fa semnum
 189 argument
 190 is not in the range of valid semaphores for given semaphore set.
 191 .\" ===========
 192 .It Bq Er EPERM
 193 The calling process's effective uid does not match the uid of
 194 the semaphore set's owner or creator.
 195 .\" ===========
 196 .It Bq Er ERANGE
 197 .Dv SETVAL
 198 or
 199 .Dv SETALL
 200 attempted to set a semaphore outside the allowable range
 201 .Bq 0 .. Dv SEMVMX .
 202 .El
 203 .Sh LEGACY SYNOPSIS
 204 .Fd #include <sys/types.h>
 205 .Fd #include <sys/ipc.h>
 206 .Fd #include <sys/sem.h>
 207 .Pp
 208 The include files
 209 .In sys/types.h
 210 and
 211 .In sys/ipc.h
 212 are necessary.
 213 .Sh SEE ALSO
 214 .Xr semget 2 ,
 215 .Xr semop 2 ,
 216 .Xr compat 5
 217 .Sh BUGS
 218 .Dv SETALL
 219 may update some semaphore elements before returning an error.