path: root/usr/src/man/man2/semctl.2

'\" 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 <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>

\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)