unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

semctl(2)                        System Calls                        semctl(2)



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 opera-
       tions 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 oper-
       ations 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 cor-
                       responding  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 exe-
                       cuted, the semadj values corresponding to  each  speci-
                       fied 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 exe-
                       cuted 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 fol-
       lows:

       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 com-
                       mand 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:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE TYPEATTRIBUTE VALUE Interface StabilityStan-
       dard


SEE ALSO
       ipcs(1), intro(2), semget(2), semop(2),  attributes(5),  privileges(5),
       standards(5)



SunOS 5.10                        1 Feb 2003                         semctl(2)