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]
 SEMCTL 2 "Feb 1, 2003"
 NAME
semctl - semaphore control operations
 SYNOPSIS

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>

int semctl(int semid, int semnum, int cmd...);


 DESCRIPTION

The semctl() function provides a variety of semaphore control operations
as specified by cmd. The fourth argument is optional, depending upon the
operation requested. If required, it is of type union semun, which
must be explicitly declared by the application program.
union semun {
 int val;
 struct semid_ds *buf;
 ushort_t *array;
} arg ;


The permission required for a semaphore operation is given as {token},
where token is the type of permission needed. The types of permission
are interpreted as follows:
00400 READ by user
00200 ALTER by user
00040 READ by group
00020 ALTER by group
00004 READ by others
00002 ALTER by others


See the Semaphore Operation Permissions subsection of the
DEFINITIONS section of Intro(2) for more information. The following
semaphore operations as specified by cmd are executed with respect to the
semaphore specified by semid and semnum.
GETVAL

Return the value of semval (see Intro(2)). {READ}


SETVAL

Set the value of semval to arg.val. {ALTER} When this
command is successfully executed, the semadj value corresponding to the
specified semaphore in all processes is cleared.


GETPID

Return the value of (int) sempid. {READ}


GETNCNT

Return the value of semncnt. {READ}


GETZCNT

Return the value of semzcnt. {READ}


The following operations return and set, respectively, every semval in
the set of semaphores.
GETALL

Place semvals into array pointed to by arg.array. {READ}


SETALL

Set semvals according to the array pointed to by arg.array.
{ALTER}. When this cmd is successfully executed, the semadj values
corresponding to each specified semaphore in all processes are cleared.


The following operations are also available.
IPC_STAT

Place the current value of each member of the data structure associated with
semid into the structure pointed to by arg.buf. The contents
of this structure are defined in Intro(2). {READ}


IPC_SET

Set the value of the following members of the data structure associated with
semid to the corresponding value found in the structure pointed to by
arg.buf:
sem_perm.uid
sem_perm.gid
sem_perm.mode /* access permission bits only */


This command can be executed only by a process that has either the
{PRIV_IPC_OWNER} privilege or an effective user ID equal to the
value of msg_perm.cuid or msg_perm.uid in the data structure
associated with msqid. Only a process with the
{PRIV_SYS_IPC_CONFIG} privilege can raise the value of msg_qbytes.


IPC_RMID

Remove the semaphore identifier specified by semid 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 {PRIV_IPC_OWNER}
privilege or an effective user ID equal to the value of
sem_perm.cuid or sem_perm.uid in the data structure associated with
semid.


 RETURN VALUES

Upon successful completion, the value returned depends on cmd as follows:
GETVAL

the value of semval


GETPID

the value of (int) sempid


GETNCNT

the value of semncnt


GETZCNT

the value of semzcnt


All other successful completions return 0; otherwise, -1 is
returned and errno is set to indicate the error.
 ERRORS

The semctl() function will fail if:
EACCES

Operation permission is denied to the calling process (see Intro(2)).


EFAULT

The source or target is not a valid address in the user process.


EINVAL

The semid argument is not a valid semaphore identifier; the semnum
argument is less than 0 or greater than sem_nsems -1; or the cmd
argument is not a valid command or is IPC_SET and sem_perm.uid or
sem_perm.gid is not valid.


EPERM

The cmd argument is equal to IPC_RMID or IPC_SET, the
effective user ID of the calling process is not equal to the value of
sem_perm.cuid or sem_perm.uid in the data structure associated with
semid, and {PRIV_IPC_OWNER} is not asserted in the effective set of
the calling process.


EOVERFLOW

The cmd argument is IPC_STAT and uid or gid is too
large to be stored in the structure pointed to by arg.buf.


ERANGE

The cmd argument is SETVAL or SETALL and the value to which
semval is to be set is greater than the system imposed maximum.


 ATTRIBUTES

See attributes(5) for descriptions of the following attributes:


ATTRIBUTE TYPE ATTRIBUTE VALUE
Interface Stability Standard


 SEE ALSO

ipcs(1), Intro(2), semget(2), semop(2),
attributes(5), privileges(5), standards(5)