usr/src/man/man2/semctl.2

   1 '\" te
   2 .\" Copyright 1989 AT&T.  Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SEMCTL 2 "Feb 1, 2003"
   7 .SH NAME
   8 semctl \- semaphore control operations
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <sys/ipc.h>
  14 #include <sys/sem.h>
  15
  16 \fBint\fR \fBsemctl\fR(\fBint\fR \fIsemid\fR, \fBint\fR \fIsemnum\fR, \fBint\fR \fIcmd\fR...);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBsemctl()\fR function provides a variety of semaphore control operations
  23 as specified by \fIcmd\fR. The fourth argument is optional, depending upon the
  24 operation  requested.  If required, it is of type  \fBunion semun\fR, which
  25 must be explicitly declared by the application program.
  26 .sp
  27 .in +2
  28 .nf
  29 union semun {
  30         int             val;
  31         struct semid_ds *buf;
  32         ushort_t        *array;
  33 } arg ;
  34 .fi
  35 .in -2
  36
  37 .sp
  38 .LP
  39 The permission required for a semaphore operation is given as {\fItoken\fR},
  40 where \fItoken\fR is the type of permission needed.  The types of permission
  41 are interpreted as follows:
  42 .sp
  43 .in +2
  44 .nf
  45 00400    READ by user
  46 00200    ALTER by user
  47 00040    READ by group
  48 00020    ALTER by group
  49 00004    READ by others
  50 00002    ALTER by others
  51 .fi
  52 .in -2
  53
  54 .sp
  55 .LP
  56 See the \fBSemaphore Operation Permissions\fR subsection of the
  57 \fBDEFINITIONS\fR section of \fBIntro\fR(2) for more information. The following
  58 semaphore operations as specified by \fIcmd\fR are executed with respect to the
  59 semaphore specified by \fIsemid\fR and \fIsemnum\fR.
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fBGETVAL\fR\fR
  64 .ad
  65 .RS 11n
  66 Return the value of  semval (see \fBIntro\fR(2)). {READ}
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fBSETVAL\fR\fR
  73 .ad
  74 .RS 11n
  75 Set the value of  \fBsemval\fR to \fIarg.\fR\fIval\fR. {ALTER} When this
  76 command is successfully executed, the \fBsemadj\fR value corresponding to the
  77 specified semaphore in all processes is cleared.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBGETPID\fR\fR
  84 .ad
  85 .RS 11n
  86 Return the value of \fB(int) sempid\fR. {READ}
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBGETNCNT\fR\fR
  93 .ad
  94 .RS 11n
  95 Return the value of \fBsemncnt\fR. {READ}
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBGETZCNT\fR\fR
 102 .ad
 103 .RS 11n
 104 Return the value of \fBsemzcnt\fR. {READ}
 105 .RE
 106
 107 .sp
 108 .LP
 109 The following operations return and set, respectively, every \fBsemval\fR in
 110 the set of semaphores.
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBGETALL\fR\fR
 115 .ad
 116 .RS 10n
 117 Place \fBsemval\fRs into array pointed to by \fIarg.\fR\fBarray\fR. {READ}
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBSETALL\fR\fR
 124 .ad
 125 .RS 10n
 126 Set \fBsemval\fRs according to the array pointed to by \fIarg.\fR\fBarray\fR.
 127 {ALTER}. When this cmd is successfully executed, the \fBsemadj\fR values
 128 corresponding to each specified semaphore in all processes are cleared.
 129 .RE
 130
 131 .sp
 132 .LP
 133 The following operations are also available.
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBIPC_STAT\fR\fR
 138 .ad
 139 .RS 12n
 140 Place the current value of each member of the data structure associated with
 141 \fIsemid\fR into the structure pointed to by \fIarg.\fR\fBbuf\fR. The contents
 142 of this structure are defined in \fBIntro\fR(2). {READ}
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fBIPC_SET\fR\fR
 149 .ad
 150 .RS 12n
 151 Set the value of the following members of the data structure associated with
 152 \fIsemid\fR to the corresponding value found in the structure pointed to by
 153 \fIarg\fR.\fBbuf\fR:
 154 .sp
 155 .in +2
 156 .nf
 157 sem_perm.uid
 158 sem_perm.gid
 159 sem_perm.mode   /* access permission bits only */
 160 .fi
 161 .in -2
 162
 163 This command can be executed only by a process that has either the
 164 {\fBPRIV_IPC_OWNER\fR} privilege or an effective user \fBID\fR equal to the
 165 value of \fBmsg_perm.cuid\fR or \fBmsg_perm.uid\fR in the data structure
 166 associated with \fImsqid\fR. Only a process with the
 167 {\fBPRIV_SYS_IPC_CONFIG\fR} privilege can raise the value of \fBmsg_qbytes\fR.
 168 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fBIPC_RMID\fR\fR
 174 .ad
 175 .RS 12n
 176 Remove the semaphore identifier specified by \fIsemid\fR from the system and
 177 destroy the set of semaphores and data structure associated with it. This
 178 command can be executed only by a process that has the {\fBPRIV_IPC_OWNER\fR}
 179 privilege or an effective user \fBID\fR equal to the value of
 180 \fBsem_perm.cuid\fR or \fBsem_perm.uid\fR in the data structure associated with
 181 \fIsemid\fR.
 182 .RE
 183
 184 .SH RETURN VALUES
 185 .sp
 186 .LP
 187 Upon successful completion, the value returned depends on \fIcmd\fR as follows:
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fBGETVAL\fR\fR
 192 .ad
 193 .RS 11n
 194 the value of \fBsemval\fR
 195 .RE
 196
 197 .sp
 198 .ne 2
 199 .na
 200 \fB\fBGETPID\fR\fR
 201 .ad
 202 .RS 11n
 203 the value of \fB(int) sempid\fR
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fBGETNCNT\fR\fR
 210 .ad
 211 .RS 11n
 212 the value of \fBsemncnt\fR
 213 .RE
 214
 215 .sp
 216 .ne 2
 217 .na
 218 \fB\fBGETZCNT\fR\fR
 219 .ad
 220 .RS 11n
 221 the value of \fBsemzcnt\fR
 222 .RE
 223
 224 .sp
 225 .LP
 226 All other successful completions return  \fB0\fR; otherwise, \fB\(mi1\fR is
 227 returned and \fBerrno\fR is set to indicate the error.
 228 .SH ERRORS
 229 .sp
 230 .LP
 231 The \fBsemctl()\fR function will fail if:
 232 .sp
 233 .ne 2
 234 .na
 235 \fB\fBEACCES\fR\fR
 236 .ad
 237 .RS 13n
 238 Operation permission is denied to the calling process (see \fBIntro\fR(2)).
 239 .RE
 240
 241 .sp
 242 .ne 2
 243 .na
 244 \fB\fBEFAULT\fR\fR
 245 .ad
 246 .RS 13n
 247 The source or target is not a valid address in the user process.
 248 .RE
 249
 250 .sp
 251 .ne 2
 252 .na
 253 \fB\fBEINVAL\fR\fR
 254 .ad
 255 .RS 13n
 256 The \fIsemid\fR argument is not a valid semaphore identifier; the \fIsemnum\fR
 257 argument is less than 0 or greater than \fBsem_nsems\fR \(mi1; or the \fIcmd\fR
 258 argument is not a valid command or is \fBIPC_SET\fR and \fBsem_perm.uid\fR or
 259 \fBsem_perm.gid\fR is not valid.
 260 .RE
 261
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fBEPERM\fR\fR
 266 .ad
 267 .RS 13n
 268 The \fIcmd\fR argument is equal to \fBIPC_RMID\fR or \fBIPC_SET\fR, the
 269 effective user ID of the calling process is not equal to the value of
 270 \fBsem_perm.cuid\fR or \fBsem_perm.uid\fR in the data structure associated with
 271 \fIsemid\fR, and {\fBPRIV_IPC_OWNER\fR} is not asserted in the effective set of
 272 the calling process.
 273 .RE
 274
 275 .sp
 276 .ne 2
 277 .na
 278 \fB\fBEOVERFLOW\fR\fR
 279 .ad
 280 .RS 13n
 281 The \fIcmd\fR argument is \fBIPC_STAT\fR and \fIuid\fR or \fIgid\fR is too
 282 large to be stored in the structure pointed to by \fIarg.buf\fR.
 283 .RE
 284
 285 .sp
 286 .ne 2
 287 .na
 288 \fB\fBERANGE\fR\fR
 289 .ad
 290 .RS 13n
 291 The \fIcmd\fR argument is \fBSETVAL\fR or \fBSETALL\fR and the value to which
 292 \fBsemval\fR is to be set is greater than the system imposed maximum.
 293 .RE
 294
 295 .SH ATTRIBUTES
 296 .sp
 297 .LP
 298 See \fBattributes\fR(5) for descriptions of the following attributes:
 299 .sp
 300
 301 .sp
 302 .TS
 303 box;
 304 c | c
 305 l | l .
 306 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 307 _
 308 Interface Stability     Standard
 309 .TE
 310
 311 .SH SEE ALSO
 312 .sp
 313 .LP
 314 \fBipcs\fR(1), \fBIntro\fR(2), \fBsemget\fR(2), \fBsemop\fR(2),
 315 \fBattributes\fR(5), \fBprivileges\fR(5), \fBstandards\fR(5)