*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->OpenBSD man pages -> semctl (2)              



NAME    [Toc]    [Back]

     semctl - semaphore control operations

SYNOPSIS    [Toc]    [Back]

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

     semctl(int semid, int semnum, int cmd, union semun arg);

DESCRIPTION    [Toc]    [Back]

     The semctl() system call provides a number of control operations on the
     semaphore  specified  by semnum and semid.  The operation to
be performed
     is specified in cmd (see below).  arg is a union of the following fields:

             int      val;                    /* value for SETVAL
             struct   semid_ds  *buf;           /*   buffer   for
             u_short  *array;                 /* array for GETALL

     The semid_ds  structure used in  the  IPC_SET  and  IPC_STAT
commands is defined
 as follows in <sys/sem.h>:

     struct semid_ds {
             struct ipc_perm sem_perm;       /* operation permissions */
             struct  sem *sem_base;          /* semaphore set */
             u_short sem_nsems;              /* number of sems in
set */
             time_t   sem_otime;               /*  last operation
time */
             time_t  sem_ctime;              /* last change  time

     The  ipc_perm  structure used inside the semid_ds  structure
is defined in
     <sys/ipc.h> and looks like this:

     struct ipc_perm {
             uid_t   cuid;           /* creator user id */
             gid_t   cgid;           /* creator group id */
             uid_t   uid;            /* user id */
             gid_t   gid;            /* group id */
             mode_t   mode;            /*  r/w  permission   (see
chmod(2)) */
             u_short  seq;             /* sequence # (to generate
unique msg/sem/shm id) */
             key_t   key;                 /*    user    specified
msg/sem/shm key */

     semctl() provides the following operations:

     GETVAL     Return the value of the semaphore.

     SETVAL     Set the value of the semaphore to arg.val.

     GETPID      Return  the  pid of the last process that did an
operation on
                this semaphore.

     GETNCNT    Return the number of processes waiting to acquire

     GETZCNT     Return  the  number of processes waiting for the
value of the
                semaphore to reach 0.

     GETALL     Return the values for all the semaphores  associated with

     SETALL      Set  the  values for all the semaphores that are
associated with
                the semaphore identifier semid to the corresponding values in

     IPC_STAT   Gather statistics about a semaphore and place the
                in the semid_ds  structure pointed to by  arg.buf
(see above).

     IPC_SET     Set  the value of the sem_perm.uid, sem_perm.gid
                sem_perm.mode fields in the structure  associated
with the
                semaphore.   The values are taken from the corresponding fields
                in the structure pointed to by arg.buf.  This operation can
                only  be  executed by the superuser, or a process
that has an
                effective user ID equal to  either  sem_perm.cuid
                sem_perm.uid  in  the  data  structure associated
with the message

     IPC_RMID   Remove the semaphores associated with semid  from
the system
                and  destroy  the data structures associated with
it.  Only the
                superuser or a  process  with  an  effective  UID
equal to the
                sem_perm.cuid  or sem_perm.uid values in the data
structure associated
 with the semaphore can do this.

     The permission to read or change a message  queue  (see  semop(2)) is determined
  by the sem_perm.mode field in the same way as is done
with files
     (see chmod(2)), but the effective UID can match  either  the
     field  or  the sem_perm.uid field, and the effective GID can
match either
     sem_perm.cgid or sem_perm.gid.

RETURN VALUES    [Toc]    [Back]

     For the GETVAL, GETPID,  GETNCNT,  and  GETZCNT  operations,
semctl() returns
     one  of the values described above if successful.  All other
     will make semctl() return 0 if no errors  occur.   Otherwise
-1 is returned
     and errno set to reflect the error.

ERRORS    [Toc]    [Back]

     semctl() will fail if:

     [EPERM]        cmd  is  equal to IPC_SET or IPC_RMID and the
caller is not
                   the superuser,  nor  does  the  effective  UID
match either the
                   sem_perm.uid  or  sem_perm.cuid  fields of the
data structure
                   associated with the message queue.

     [EACCES]      The caller has  no  operation  permission  for
this semaphore.

     [EINVAL]      semid is not a valid message semaphore identifier.

                   cmd is not a valid command.

     [EFAULT]      arg.buf specifies an invalid address.

SEE ALSO    [Toc]    [Back]

     semget(2), semop(2)

OpenBSD     3.6                         August      17,      1995
[ Back ]
 Similar pages
Name OS Title
semctl FreeBSD control operations on a semaphore set
semctl Tru64 Perform semaphore control operations
semop IRIX semaphore operations
semop OpenBSD semaphore operations
semop Linux semaphore operations
semtimedop HP-UX semaphore operations
semop HP-UX semaphore operations
semop NetBSD semaphore operations
sem_close FreeBSD named semaphore operations
sem_open FreeBSD named semaphore operations
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service