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 .Fn Semctl
  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 parameter,
  55 .Fa "union semun"
  56 is defined as follows:
  57 .Bd -literal
  58 .\"
  59 .\" From <sys/sem.h>:
  60 .\"
  61 union semun {
  62         int     val;            /* value for SETVAL */
  63         struct  semid_ds *buf;  /* buffer for IPC_STAT & IPC_SET */
  64         u_short *array;         /* array for GETALL & SETALL */
  65 };
  66 .Ed
  67 .Pp
  68 Commands are performed as follows:
  69 .\"
  70 .\" This section based on Stevens, _Advanced Programming in the UNIX
  71 .\" Environment_.
  72 .\"
  73 .Bl -tag -width IPC_RMIDXXX
  74 .It Dv IPC_STAT
  75 Fetch the semaphore set's
  76 .Fa "struct semid_ds" ,
  77 storing it in the memory pointed to by
  78 .Fa arg.buf .
  79 .It Dv IPC_SET
  80 Changes the
  81 .Fa sem_perm.uid ,
  82 .Fa sem_perm.gid ,
  83 and
  84 .Fa sem_perm.mode
  85 members of the semaphore set's
  86 .Fa "struct semid_ds"
  87 to match those of the struct pointed to by
  88 .Fa arg.buf .
  89 The calling process's effective uid must
  90 match either
  91 .Fa sem_perm.uid
  92 or
  93 .Fa sem_perm.cuid ,
  94 or it must have superuser privileges.
  95 .It IPC_RMID
  96 Immediately removes the semaphore set from the system.  The calling
  97 process's effective uid must equal the semaphore set's
  98 .Fa sem_perm.uid
  99 or
 100 .Fa sem_perm.cuid ,
 101 or the process must have superuser privileges.
 102 .It Dv GETVAL
 103 Return the value of semaphore number
 104 .Fa semnum .
 105 .It Dv SETVAL
 106 Set the value of semaphore number
 107 .Fa semnum
 108 to
 109 .Fa arg.val .
 110 Outstanding adjust on exit values for this semaphore in any process
 111 are cleared.
 112 .It Dv GETPID
 113 Return the pid of the last process to perform an operation on
 114 semaphore number
 115 .Fa semnum .
 116 .It Dv GETNCNT
 117 Return the number of processes waiting for semaphore number
 118 .Fa semnum Ns 's
 119 value to become greater than its current value.
 120 .It Dv GETZCNT
 121 Return the number of processes waiting for semaphore number
 122 .Fa semnum Ns 's
 123 value to become 0.
 124 .It Dv GETALL
 125 Fetch the value of all of the semaphores in the set into the
 126 array pointed to by
 127 .Fa arg.array .
 128 .It Dv SETALL
 129 Set the values of all of the semaphores in the set to the values
 130 in the array pointed to by
 131 .Fa arg.array .
 132 Outstanding adjust on exit values for all semaphores in this set,
 133 in any process are cleared.
 134 .El
 135 .Pp
 136 The
 137 .Fa "struct semid_ds"
 138 is defined as follows:
 139 .Bd -literal
 140 .\"
 141 .\" Taken straight from <sys/sem.h>.
 142 .\"
 143 struct semid_ds {
 144         struct  ipc_perm sem_perm;      /* operation permission struct */
 145         struct  sem *sem_base;  /* pointer to first semaphore in set */
 146         u_short sem_nsems;      /* number of sems in set */
 147         time_t  sem_otime;      /* last operation time */
 148         long    sem_pad1;       /* SVABI/386 says I need this here */
 149         time_t  sem_ctime;      /* last change time */
 150                                 /* Times measured in secs since */
 151                                 /* 00:00:00 GMT, Jan. 1, 1970 */
 152         long    sem_pad2;       /* SVABI/386 says I need this here */
 153         long    sem_pad3[4];    /* SVABI/386 says I need this here */
 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 .Fn Semctl
 170 will fail if:
 171 .Bl -tag -width Er
 172 .It Bq Er EINVAL
 173 No semaphore set corresponds to
 174 .Fa semid .
 175 .It Bq Er EINVAL
 176 .Fa semnum
 177 is not in the range of valid semaphores for given semaphore set.
 178 .It Bq Er EPERM
 179 The calling process's effective uid does not match the uid of
 180 the semaphore set's owner or creator.
 181 .It Bq Er EACCES
 182 Permission denied due to mismatch between operation and mode of
 183 semaphore set.
 184 .It Bq Er ERANGE
 185 .Dv SETVAL
 186 or
 187 .Dv SETALL
 188 attempted to set a semaphore outside the allowable range
 189 .Bq 0 .. Dv SEMVMX .
 190 .El
 191 .Sh SEE ALSO
 192 .Xr semget 2 ,
 193 .Xr semop 2
 194 .Sh BUGS
 195 .Dv SETALL
 196 may update some semaphore elements before returning an error.