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: src/lib/libc/sys/semctl.2,v 1.9.2.6 2002/03/11 08:37:47 maxim Exp $
  27 .\"
  28 .Dd January 4, 2014
  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 .It Dv GETPID
 111 Return the pid of the last process to perform an operation on
 112 semaphore number
 113 .Fa semnum .
 114 .It Dv GETNCNT
 115 Return the number of processes waiting for semaphore number
 116 .Fa semnum Ns 's
 117 value to become greater than its current value.
 118 .It Dv GETZCNT
 119 Return the number of processes waiting for semaphore number
 120 .Fa semnum Ns 's
 121 value to become 0.
 122 .It Dv GETALL
 123 Fetch the value of all of the semaphores in the set into the
 124 array pointed to by
 125 .Fa arg.array .
 126 .It Dv SETALL
 127 Set the values of all of the semaphores in the set to the values
 128 in the array pointed to by
 129 .Fa arg.array .
 130 .El
 131 .Pp
 132 The
 133 .Fa "struct semid_ds"
 134 is defined as follows:
 135 .Bd -literal
 136 .\"
 137 .\" Taken straight from <sys/sem.h>.
 138 .\"
 139 struct semid_ds {
 140         struct  ipc_perm sem_perm;      /* operation permission struct */
 141         struct  sem *sem_base;  /* pointer to first semaphore in set */
 142         u_short sem_nsems;      /* number of sems in set */
 143         time_t  sem_otime;      /* last operation time */
 144         long    sem_pad1;       /* SVABI/386 says I need this here */
 145         time_t  sem_ctime;      /* last change time */
 146                                 /* Times measured in secs since */
 147                                 /* 00:00:00 GMT, Jan. 1, 1970 */
 148         long    sem_pad2;       /* SVABI/386 says I need this here */
 149         long    sem_pad3[4];    /* SVABI/386 says I need this here */
 150 };
 151 .Ed
 152 .Sh RETURN VALUES
 153 On success, when
 154 .Fa cmd
 155 is one of
 156 .Dv GETVAL , GETPID , GETNCNT
 157 or
 158 .Dv GETZCNT ,
 159 .Fn semctl
 160 returns the corresponding value; otherwise, 0 is returned.
 161 On failure, -1 is returned, and
 162 .Va errno
 163 is set to indicate the error.
 164 .Sh ENVIRONMENT
 165 The XSI Interprocess Communication family of functions is also available
 166 as an implementation in userspace.
 167 To use it, the
 168 .Xr sysvipcd 8
 169 daemon has to be running.
 170 .Pp
 171 If the
 172 .Ev USR_SYSVIPC
 173 variable is set in a process' environment, the process and its children
 174 will use the userspace implementation.
 175 .Sh ERRORS
 176 .Fn Semctl
 177 will fail if:
 178 .Bl -tag -width Er
 179 .It Bq Er EINVAL
 180 No semaphore set corresponds to
 181 .Fa semid .
 182 .It Bq Er EINVAL
 183 .Fa semnum
 184 is not in the range of valid semaphores for given semaphore set.
 185 .It Bq Er EPERM
 186 The calling process's effective uid does not match the uid of
 187 the semaphore set's owner or creator.
 188 .It Bq Er EACCES
 189 Permission denied due to mismatch between operation and mode of
 190 semaphore set.
 191 .El
 192 .Sh SEE ALSO
 193 .Xr semget 2 ,
 194 .Xr semop 2
 195 .Sh AUTHORS
 196 .An -nosplit
 197 The
 198 .Dx
 199 specific userspace implementation (see
 200 .Sx ENVIRONMENT )
 201 was written by
 202 .An Larisa Grigore .