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

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
       The  function returns the semaphore set identifier associ-
       ated to the value of the argument key.  A new set of nsems
       semaphores  is created if key has value IPC_PRIVATE or key
       isn't IPC_PRIVATE, no existing message queue 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 existence of  the  semaphore  set,  as  the
       presence of O_CREAT and O_EXCL in the mode argument of the
       open(2) 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 lower 9 bits  of  the  argument  semflg
       define  the  access permissions (for owner, group and oth-
       ers) to the semaphore set in the same format, and with the
       same  meaning,  as for the access permissions parameter in
       the open(2) or creat(2) system calls (though  the  execute
       permissions  are not used by the system, and write permis-
       sions, for a semaphore set, effectively means  alter  per-
       missions).

       Furthermore,  while  creating, the system call initializes
       the system semaphore set 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 lowest order 9 bits of sem_perm.mode are set to
              the lowest order 9 bit 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 the system
       call  isn't a create one.  Otherwise nsems must be greater
       than 0  and  less  or  equal  to  the  maximum  number  of
       semaphores per semid, (SEMMSL).

       If  the  semaphore  set already exists, the access permis-
       sions are verified, and a check is made to see  if  it  is
       marked for destruction.

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

ERRORS
       For  a  failing return, errno will be set to one among the
       following values:

       EACCES     A semaphore set exists for key, but the calling
                  process has no access permissions to the set.

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

       EIDRM      The semaphore set is marked as to be deleted.

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

       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 lowest order 9 bits of semflg and cre-
       ates 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.

       As for the files, 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 cre-
       ated, 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(2) to  perform  a  SETVAL  or  a
       SETALL command on the semaphore set.

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

SEE ALSO
       ftok(3), ipc(5), semctl(2), semop(2).

Linux 0.99.13            November 1, 1993                       1