semctl(PCI)                    6 January 1993                    semctl(PCI)


 Name

    semctl - semaphore control operations

 Syntax


    #include <pcilib.h>


    #include <memmdl.h>


    #include <ipc.h>

    int semctl (semid, semnum, cmd, arg)
    int semid, semnum, cmd;
    union semun {
       int val;
       struct semid_ds *buf;
       ushort *array;
    } arg;


 Description

    semctl provides a variety of semaphore control operations as specified by
    cmd.  The operations are performed on the current host (as specified in
    the most recent dflthost call).

    The following cmds are executed with respect to the semaphore specified
    by semid and semnum:

    GETVAL   Return the value of semval; see Intro(PCI).

    SETVAL   Set the value of semval to arg.val. When this cmd is success-
             fully executed, the semadj value corresponding to the specified
             semaphore in all UNIX operating system processes is cleared.

    GETPID   Return the value of sempid.

    GETNCNT  Return the value of semncnt.

    GETZCNT  Return the value of semzcnt.

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

    GETALL  Place semvals into the array pointed to by arg.array.

    SETALL  Set semvals according to the array pointed to by arg.array. When
            this cmd is successfully executed, the semadj values corre-
            sponding to each specified semaphore in all UNIX operating system
            processes are cleared.

    The following cmds are also available:

    IPCSTAT  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(PCI).

    IPCSET   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        /* only low nine bits */


    This cmd can only be executed by a process that has an effective user ID
    equal to either that of super-user or to the value of semperm.[c]uid in
    the data structure associated with semid.

    IPCRMID  Remove the semaphore identifier specified by semid from a UNIX
              operating system and destroy the set of semaphores and data
              structure associated with it.  This cmd can only be executed by
              a process that has an effective user ID equal to either that of
              super-user or to the value of semperm.[c]uid in the data
              structure associated with semid.

    semctl fails if one or more of the following are true:

    [EINVAL]  semid is not a valid semaphore identifier.

    [EINVAL]  semnum is less than zero or greater than semnsems.

    [EINVAL]  cmd is not a valid command.

    [EACCES]  Operation permission is denied to the calling process; see
              Intro(PCI).

    [ERANGE]  cmd is SETVAL or SETALL and the value to which semval is to be
              set is greater than the UNIX operating system-imposed maximum.

    [EPERM]   cmd is equal to IPCRMID or IPCSET, and the effective user ID
              of the calling process is not equal to that of super-user, and
              it is not equal to the value of semperm.[c]uid in the data
              structure associated with semid.

    [EFAULT]  arg.buf points to an illegal address.


 Return value

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

    GETVAL   is the value of semval.

    GETPID   is the value of sempid.

    GETNCNT  is the value of semncnt.

    GETZCNT  is the value of semzcnt.

    All others have a value of 0.

    If the operation fails, a value of -1 returns and errno is set to indi-
    cate the error.

 See also

    dflthost(PCI), Intro(PCI), semget(PCI), semop(PCI)