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 associated
     to  the value of the argument key.  A new set of nsems sema-
     phores 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  msgget  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 others)
     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 permis-
     sions are not used by the system, and write permissions, for
     a semaphore set, effectively means alter permissions).

     Furthermore, while creating, the system call initializes the
     system semaphore set data structure semid_ds as follows:

          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  permissions
     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  system
                has not enough memory for the new data structure.

     ENOSPC     A semaphore set has to be created but the  system
                limit  for  the  maximum number of semaphore sets
                (SEMMNI), or the system wide  maximum  number  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 creates
     a new semaphore set (on success).

     The followings are limits on semaphore set resources affect-
     ing a semget call:

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

     SEMMSL     Maximum number of semaphores per semid: implemen-
                tation dependent (500 currently).

     SEMMNS     System wide maximum number of semaphores:  policy
                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 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 initial-
     ize 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 EIN-
     VAL, EFBIG, E2BIG, EAGAIN, ERANGE, EFAULT.


SEE ALSO

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