# semctl

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           semctl — XSI semaphore control operations
    


## SYNOPSIS



           #include <sys/sem.h>
    
           int semctl(int _semid_ , int _semnum_ , int _cmd_ , ...);
    


## DESCRIPTION



           The _semctl_() function operates on XSI semaphores (see the Base
           Definitions volume of POSIX.1‐2017, _Section 4.17_ , _Semaphore_).  It
           is unspecified whether this function interoperates with the
           realtime interprocess communication facilities defined in _Section_
           _2.8_ , _Realtime_.
    
           The _semctl_() function provides a variety of semaphore control
           operations as specified by _cmd_.  The fourth argument is optional
           and depends upon the operation requested. If required, it is of
           type **union semun** , which the application shall explicitly declare:
    
               union semun {
                   int val;
                   struct semid_ds *buf;
                   unsigned short  *array;
               } arg;
    
           Each operation shall be performed atomically.
    
           The following semaphore control operations as specified by _cmd_ are
           executed with respect to the semaphore specified by _semid_ and
           _semnum_.  The level of permission required for each operation is
           shown with each command; see _Section 2.7_ , _XSI Interprocess_
           _Communication_.  The symbolic names for the values of _cmd_ are
           defined in the _< sys/sem.h>_ header:
    
           GETVAL      Return the value of _semval_ ; see _< sys/sem.h>_.  Requires
                       read permission.
    
           SETVAL      Set the value of _semval_ to _arg.val_ , where _arg_ is the
                       value of the fourth argument to _semctl_().  When this
                       command is successfully executed, the _semadj_ value
                       corresponding to the specified semaphore in all
                       processes is cleared. Also, the _sem_ctime_ timestamp
                       shall be set to the current time, as described in
                       _Section 2.7.1_ , _IPC General Description_.  Requires
                       alter permission; see _Section 2.7_ , _XSI Interprocess_
                       _Communication_.
    
           GETPID      Return the value of _sempid_.  Requires read permission.
    
           GETNCNT     Return the value of _semncnt_.  Requires read
                       permission.
    
           GETZCNT     Return the value of _semzcnt_.  Requires read
                       permission.
    
           The following values of _cmd_ operate on each _semval_ in the set of
           semaphores:
    
           GETALL      Return the value of _semval_ for each semaphore in the
                       semaphore set and place into the array pointed to by
                       _arg.array_ , where _arg_ is the fourth argument to
                       _semctl_().  Requires read permission.
    
           SETALL      Set the value of _semval_ for each semaphore in the
                       semaphore set according to the array pointed to by
                       _arg.array_ , where _arg_ is the fourth argument to
                       _semctl_().  When this command is successfully executed,
                       the _semadj_ values corresponding to each specified
                       semaphore in all processes are cleared. Also, the
                       _sem_ctime_ timestamp shall be set to the current time,
                       as described in _Section 2.7.1_ , _IPC General_
                       _Description_.  Requires alter permission.
    
           The following values of _cmd_ are also available:
    
           IPC_STAT    Place the current value of each member of the **semid_ds**
                       data structure associated with _semid_ into the
                       structure pointed to by _arg.buf_ , where _arg_ is the
                       fourth argument to _semctl_().  The contents of this
                       structure are defined in _< sys/sem.h>_.  Requires read
                       permission.
    
           IPC_SET     Set the value of the following members of the **semid_ds**
                       data structure associated with _semid_ to the
                       corresponding value found in the structure pointed to
                       by _arg.buf_ , where _arg_ is the fourth argument to
                       _semctl_():
    
                           sem_perm.uid
                           sem_perm.gid
                           sem_perm.mode
    
                       The mode bits specified in _Section 2.7.1_ , _IPC General_
                       _Description_ are copied into the corresponding bits of
                       the _sem_perm.mode_ associated with _semid_.  The stored
                       values of any other bits are unspecified. The
                       _sem_ctime_ timestamp shall be set to the current time,
                       as described in _Section 2.7.1_ , _IPC General_
                       _Description_.
    
                       This command can only be executed by a process that
                       has an effective user ID equal to either that of a
                       process with appropriate privileges or to the value of
                       _sem_perm.cuid_ or _sem_perm.uid_ in the **semid_ds** data
                       structure associated with _semid_.
    
           IPC_RMID    Remove the semaphore identifier specified by _semid_
                       from the system and destroy the set of semaphores and
                       **semid_ds** data structure associated with it. This
                       command can only be executed by a process that has an
                       effective user ID equal to either that of a process
                       with appropriate privileges or to the value of
                       _sem_perm.cuid_ or _sem_perm.uid_ in the **semid_ds** data
                       structure associated with _semid_.
    


## RETURN VALUE



           If successful, the value returned by _semctl_() depends on _cmd_ as
           follows:
    
           GETVAL      The value of _semval_.
    
           GETPID      The value of _sempid_.
    
           GETNCNT     The value of _semncnt_.
    
           GETZCNT     The value of _semzcnt_.
    
           All others  0.
    
           Otherwise, _semctl_() shall return -1 and set _errno_ to indicate the
           error.
    


## ERRORS



           The _semctl_() function shall fail if:
    
           **EACCES** Operation permission is denied to the calling process; see
                  _Section 2.7_ , _XSI Interprocess Communication_.
    
           **EINVAL** The value of _semid_ is not a valid semaphore identifier, or
                  the value of _semnum_ is less than 0 or greater than or equal
                  to _sem_nsems_ , or the value of _cmd_ is not a valid command.
    
           **EPERM** The argument _cmd_ is equal to IPC_RMID or IPC_SET and the
                  effective user ID of the calling process is not equal to
                  that of a process with appropriate privileges and it is not
                  equal to the value of _sem_perm.cuid_ or _sem_perm.uid_ in the
                  data structure associated with _semid_.
    
           **ERANGE** The argument _cmd_ is equal to SETVAL or SETALL and the value
                  to which _semval_ is to be set is greater than the system-
                  imposed maximum.
    
           _The following sections are informative._
    


## EXAMPLES



           Refer to semop(3p).
    


## APPLICATION USAGE



           The fourth parameter in the SYNOPSIS section is now specified as
           **"..."** in order to avoid a clash with the ISO C standard when
           referring to the union _semun_ (as defined in Issue 3) and for
           backwards-compatibility.
    
           The POSIX Realtime Extension defines alternative interfaces for
           interprocess communication. Application developers who need to use
           IPC should design their applications so that modules using the IPC
           routines described in _Section 2.7_ , _XSI Interprocess Communication_
           can be easily modified to use the alternative interfaces.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *