'\" te .\" Copyright 1989 AT&T. Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved .\" 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. .\" 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. .\" 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] .TH SEMCTL 2 "Feb 1, 2003" .SH NAME semctl \- semaphore control operations .SH SYNOPSIS .LP .nf #include #include #include \fBint\fR \fBsemctl\fR(\fBint\fR \fIsemid\fR, \fBint\fR \fIsemnum\fR, \fBint\fR \fIcmd\fR...); .fi .SH DESCRIPTION .sp .LP The \fBsemctl()\fR function provides a variety of semaphore control operations as specified by \fIcmd\fR. The fourth argument is optional, depending upon the operation requested. If required, it is of type \fBunion semun\fR, which must be explicitly declared by the application program. .sp .in +2 .nf union semun { int val; struct semid_ds *buf; ushort_t *array; } arg ; .fi .in -2 .sp .LP The permission required for a semaphore operation is given as {\fItoken\fR}, where \fItoken\fR is the type of permission needed. The types of permission are interpreted as follows: .sp .in +2 .nf 00400 READ by user 00200 ALTER by user 00040 READ by group 00020 ALTER by group 00004 READ by others 00002 ALTER by others .fi .in -2 .sp .LP See the \fBSemaphore Operation Permissions\fR subsection of the \fBDEFINITIONS\fR section of \fBIntro\fR(2) for more information. The following semaphore operations as specified by \fIcmd\fR are executed with respect to the semaphore specified by \fIsemid\fR and \fIsemnum\fR. .sp .ne 2 .na \fB\fBGETVAL\fR\fR .ad .RS 11n Return the value of semval (see \fBIntro\fR(2)). {READ} .RE .sp .ne 2 .na \fB\fBSETVAL\fR\fR .ad .RS 11n Set the value of \fBsemval\fR to \fIarg.\fR\fIval\fR. {ALTER} When this command is successfully executed, the \fBsemadj\fR value corresponding to the specified semaphore in all processes is cleared. .RE .sp .ne 2 .na \fB\fBGETPID\fR\fR .ad .RS 11n Return the value of \fB(int) sempid\fR. {READ} .RE .sp .ne 2 .na \fB\fBGETNCNT\fR\fR .ad .RS 11n Return the value of \fBsemncnt\fR. {READ} .RE .sp .ne 2 .na \fB\fBGETZCNT\fR\fR .ad .RS 11n Return the value of \fBsemzcnt\fR. {READ} .RE .sp .LP The following operations return and set, respectively, every \fBsemval\fR in the set of semaphores. .sp .ne 2 .na \fB\fBGETALL\fR\fR .ad .RS 10n Place \fBsemval\fRs into array pointed to by \fIarg.\fR\fBarray\fR. {READ} .RE .sp .ne 2 .na \fB\fBSETALL\fR\fR .ad .RS 10n Set \fBsemval\fRs according to the array pointed to by \fIarg.\fR\fBarray\fR. {ALTER}. When this cmd is successfully executed, the \fBsemadj\fR values corresponding to each specified semaphore in all processes are cleared. .RE .sp .LP The following operations are also available. .sp .ne 2 .na \fB\fBIPC_STAT\fR\fR .ad .RS 12n Place the current value of each member of the data structure associated with \fIsemid\fR into the structure pointed to by \fIarg.\fR\fBbuf\fR. The contents of this structure are defined in \fBIntro\fR(2). {READ} .RE .sp .ne 2 .na \fB\fBIPC_SET\fR\fR .ad .RS 12n Set the value of the following members of the data structure associated with \fIsemid\fR to the corresponding value found in the structure pointed to by \fIarg\fR.\fBbuf\fR: .sp .in +2 .nf sem_perm.uid sem_perm.gid sem_perm.mode /* access permission bits only */ .fi .in -2 This command can be executed only by a process that has either the {\fBPRIV_IPC_OWNER\fR} privilege or an effective user \fBID\fR equal to the value of \fBmsg_perm.cuid\fR or \fBmsg_perm.uid\fR in the data structure associated with \fImsqid\fR. Only a process with the {\fBPRIV_SYS_IPC_CONFIG\fR} privilege can raise the value of \fBmsg_qbytes\fR. .RE .sp .ne 2 .na \fB\fBIPC_RMID\fR\fR .ad .RS 12n Remove the semaphore identifier specified by \fIsemid\fR from the system and destroy the set of semaphores and data structure associated with it. This command can be executed only by a process that has the {\fBPRIV_IPC_OWNER\fR} privilege or an effective user \fBID\fR equal to the value of \fBsem_perm.cuid\fR or \fBsem_perm.uid\fR in the data structure associated with \fIsemid\fR. .RE .SH RETURN VALUES .sp .LP Upon successful completion, the value returned depends on \fIcmd\fR as follows: .sp .ne 2 .na \fB\fBGETVAL\fR\fR .ad .RS 11n the value of \fBsemval\fR .RE .sp .ne 2 .na \fB\fBGETPID\fR\fR .ad .RS 11n the value of \fB(int) sempid\fR .RE .sp .ne 2 .na \fB\fBGETNCNT\fR\fR .ad .RS 11n the value of \fBsemncnt\fR .RE .sp .ne 2 .na \fB\fBGETZCNT\fR\fR .ad .RS 11n the value of \fBsemzcnt\fR .RE .sp .LP All other successful completions return \fB0\fR; otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. .SH ERRORS .sp .LP The \fBsemctl()\fR function will fail if: .sp .ne 2 .na \fB\fBEACCES\fR\fR .ad .RS 13n Operation permission is denied to the calling process (see \fBIntro\fR(2)). .RE .sp .ne 2 .na \fB\fBEFAULT\fR\fR .ad .RS 13n The source or target is not a valid address in the user process. .RE .sp .ne 2 .na \fB\fBEINVAL\fR\fR .ad .RS 13n The \fIsemid\fR argument is not a valid semaphore identifier; the \fIsemnum\fR argument is less than 0 or greater than \fBsem_nsems\fR \(mi1; or the \fIcmd\fR argument is not a valid command or is \fBIPC_SET\fR and \fBsem_perm.uid\fR or \fBsem_perm.gid\fR is not valid. .RE .sp .ne 2 .na \fB\fBEPERM\fR\fR .ad .RS 13n The \fIcmd\fR argument is equal to \fBIPC_RMID\fR or \fBIPC_SET\fR, the effective user ID of the calling process is not equal to the value of \fBsem_perm.cuid\fR or \fBsem_perm.uid\fR in the data structure associated with \fIsemid\fR, and {\fBPRIV_IPC_OWNER\fR} is not asserted in the effective set of the calling process. .RE .sp .ne 2 .na \fB\fBEOVERFLOW\fR\fR .ad .RS 13n The \fIcmd\fR argument is \fBIPC_STAT\fR and \fIuid\fR or \fIgid\fR is too large to be stored in the structure pointed to by \fIarg.buf\fR. .RE .sp .ne 2 .na \fB\fBERANGE\fR\fR .ad .RS 13n The \fIcmd\fR argument is \fBSETVAL\fR or \fBSETALL\fR and the value to which \fBsemval\fR is to be set is greater than the system imposed maximum. .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(7) for descriptions of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Interface Stability Standard .TE .SH SEE ALSO .sp .LP .BR ipcs (1), .BR Intro (2), .BR semget (2), .BR semop (2), .BR attributes (7), .BR privileges (7), .BR standards (7)