semctl() -- General Function (libc)

Control semaphore operations
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
int semctl(id, number, command, arg)
int id, command, number;
union semun {
        int value;
        struct semid_ds *buffer;
        unsigned short array[];
} arg;

The function semctl() controls the COHERENT system's semaphore facility.

A set  of semaphores  consists of  a copy of  structure semid_ds,  which is
defined in header file  <sys/sem.h>. This structure points to the set
of  semaphores,  notes  how many  semaphores  are  in  the  set, and  gives
information on  who can manipulate it, and  how.  The semaphores themselves
consist of  an array of  structures of type  sem, which is  also defined in
sem.h. When  the function semget() creates a set  of semaphores, it assigns
to that set an identification number and returns that number to the calling
process.  For details on this process, see the Lexicon entry for semget()

id identifies  the set  of semaphores to  be manipulated.  This  value must
have been  returned by a call  to semget(). number gives  the offset within
the set  identified by id of  the semaphore that interests  you.  arg gives
information to  be passed to, or received from,  the semaphore in question.
command names the operation that you want semctl() to perform.

The  following   commands  manipulate  semaphore  number   within  the  set
identified by id:

GETVAL    Return the  value of semval, which is the  field in structure sem
          that gives the address of the semaphore's text map.

SETVAL    Set semval to arg.value.  If an ``adjust value'' had been created
          for this  semaphore (by changing  or setting a  semaphore through
          semop() with the flag SEM_UNDO set), it is erased.

GETPID    Return  the value  of  sempid, which  is  the field  in sem  that
          identifies the last process to have manipulated this semaphore.

GETNCNT   Return the value of  semncnt, which gives the number of processes
          that await an increase in field sem.semval.

GETZCNT   Return the value of  semzcnt, which gives the number of processes
          that are waiting for the value of sem.semval to become zero.

The following commands return or set field semval within every semaphore in
the set identified by id:

GETALL    Write every semval into arg.array.

SETALL    Initialize  every  semval   to  the  corresponding  value  within
          arg.array.  All ``adjust values'' for this semaphores are erased.

semctl() also recognizes the following commands:

IPC_STAT  Copy the value of each semaphore in the set identified by id into
          the structure pointed to by arg.buffer.

IPC_SET   Copy  fields sem_perm.uid,  sem_perm.gid, and  sem_perm.mode (low
          nine bits  only) from the  ipc_perm associated with  id into that
          pointed to arg.buffer. Only  the superuser root or the user whose
          effective  user ID  matches the  value of field  uid in  the data
          structure identified by id can invoke this command.

IPC_RMID  Destroy the  semid_ds structure identified by  id, plus its array
          of  semaphores.   Only  the  superuser  root  or the  user  whose
          effective user ID matches the  value of field uid can invoke this
          command.

semctl() fails if one or more of the following is true:

-> id  is  not a  valid  semaphore identifier.   semctl()  sets the  global
   variable errno to EINVAL.

-> number is  less than zero  or greater than field  sem_nsems in structure
   semid_ds, which gives the number  of semaphores in the set identified by
   id (EINVAL).

-> command is not a valid command (EINVAL).

-> The calling process is denied operation permission (EACCES).

-> command is SETVAL or SETALL, but the value of semval exceeds the system-
   imposed maximum (ERANGE).

-> command is IPC_RMID or IPC_SET, but the calling process is owned neither
   by  root  nor by  the  user  who created  the  set  of semaphores  being
   manipulated (EPERM).

-> arg.buffer points to an illegal address (EFAULT).

semctl() returns  the following values upon  successful completion of their
following commands:

     Command   Return Value
     GETVAL    Value of semval
     GETPID    Value of sempid
     GETNCNT   Value of semncnt
     GETZCNT   Value of semzcnt

For  all  other  commands, semctl()  returns  zero  to indicate  successful
completion.

If it  could not  execute a command  successfully, semctl() returns  -1 and
sets errno to an appropriate value.

Files

/usr/include/sys/ipc.h
/usr/include/sys/sem.h

See Also

libc,
semget(),
semop()

Notes

For  information on  other methods of  interprocess communication,  see the
Lexicon entries for msgctl() and shmctl().

© 2012 by Stephen A. Ness