SEMGET(T)           Linux Programmer's Manual           SEMGET(T)



NAME
       semget - get a semaphore set identifier

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

       int semget(key_t key, int nsems, int semflg);

DESCRIPTION
       This function returns the semaphore set identifier associ-
       ated with the argument key.  A new set of nsems semaphores
       is  created  if  key  has  the  value IPC_PRIVATE or if no
       existing semaphore set is associated to key and  IPC_CREAT
       is  asserted  in  semflg  (i.e.   semflg & IPC_CREAT isn't
       zero).

       The  presence  in  semflg  of  the  fields  IPC_CREAT  and
       IPC_EXCL  plays  the  same role, with respect to the exis-
       tence of the semaphore set, as the presence of O_CREAT and
       O_EXCL  in  the  mode argument of the open(n) system call:
       i.e. the semget function  fails  if  semflg  asserts  both
       IPC_CREAT  and IPC_EXCL and a semaphore set already exists
       for key.

       Upon creation, the low-order 9 bits of the argument semflg
       define  the  access permissions (for owner, group and oth-
       ers) for the semaphore set.  These bits have the same for-
       mat,  and  the  same  meaning, as the mode argument in the
       open(n) or creat(t) system calls (though the execute  per-
       missions are not meaningful for semaphores, and write per-
       missions mean permission to alter semaphore values).

       When creating a new semaphore set, semget initializes  the
       semaphore set's associated data structure semid_ds as fol-
       lows:

              sem_perm.cuid  and  sem_perm.uid  are  set  to  the
              effective user-ID of the calling process.

              sem_perm.cgid  and  sem_perm.gid  are  set  to  the
              effective group-ID of the calling process.

              The low-order 9 bits of sem_perm.mode  are  set  to
              the low-order 9 bits of semflg.

              sem_nsems is set to the value of nsems.

              sem_otime is set to 0.

              sem_ctime is set to the current time.

       The  argument  nsems  can  be  0  (a  don't  care)  when a
       semaphore set is not being created.  Otherwise nsems  must
       be  greater  than  0 and less than or equal to the maximum
       number of semaphores per semaphore set (SEMMSL).

       If the semaphore set already exists,  the  access  permis-
       sions are verified.

RETURN VALUE
       If  successful, the return value will be the semaphore set
       identifier  (a  nonnegative  integer),  otherwise  -1   is
       returned, with errno indicating the error.

ERRORS
       On failure errno will be set to one of the following:

       EACCES     A semaphore set exists for key, but the calling
                  process does not have permission to access  the
                  set.

       EEXIST     A  semaphore  set exists for key and semflg was
                  asserting both IPC_CREAT and IPC_EXCL.

       ENOENT     No semaphore set  exists  for  key  and  semflg
                  wasn't asserting IPC_CREAT.

       EINVAL     nsems  is less than 0 or greater than the limit
                  on the number of semaphores per  semaphore  set
                  (SEMMSL),  or  a semaphore set corresponding to
                  key already exists, and nsems  is  larger  than
                  the number of semaphores in that set.

       ENOMEM     A  semaphore set has to be created but the sys-
                  tem has not enough  memory  for  the  new  data
                  structure.

       ENOSPC     A  semaphore set has to be created but the sys-
                  tem limit for the maximum number  of  semaphore
                  sets  (SEMMNI), or the system wide maximum num-
                  ber of semaphores (SEMMNS), would be  exceeded.

NOTES
       IPC_PRIVATE  isn't a flag field but a key_t type.  If this
       special value is used for key,  the  system  call  ignores
       everything  but the low-order 9 bits of semflg and creates
       a new semaphore set (on success).

       The followings  are  limits  on  semaphore  set  resources
       affecting a semget call:

       SEMMNI     System  wide  maximum number of semaphore sets:
                  policy dependent.

       SEMMSL     Maximum number of semaphores per semid:  imple-
                  mentation dependent (500 currently).

       SEMMNS     System  wide maximum number of semaphores: pol-
                  icy dependent.  Values greater  than  SEMMSL  *
                  SEMMNI makes it irrelevant.

BUGS
       Use  of IPC_PRIVATE doesn't inhibit to other processes the
       access to the allocated semaphore set.

       There is currently no  intrinsic  way  for  a  process  to
       ensure  exclusive  access  to  a semaphore set.  Asserting
       both IPC_CREAT and IPC_EXCL in  semflg  only  ensures  (on
       success)  that  a  new  semaphore  set will be created, it
       doesn't imply exclusive access to the semaphore set.

       The data structure associated with each semaphore  in  the
       set  isn't  initialized  by  the system call.  In order to
       initialize those data structures, one  has  to  execute  a
       subsequent  call  to  semctl(l)  to  perform a SETVAL or a
       SETALL command on the semaphore set.

CONFORMING TO
       SVr4, SVID.  SVr4 documents  additional  error  conditions
       EFBIG, E2BIG, EAGAIN, ERANGE, EFAULT.

SEE ALSO
       ftok(k), ipc(c), semctl(l), semop(p)



Linux 2.5                   2002-01-04                  SEMGET(T)