semget() -- General Function (libc)

Create or get a set of semaphores
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
semget(semkey, number, flag)
key_t semkey; int number, flag;

semget() creates a set of semaphores plus its associated data structure and
identifier, links them to the identifier semkey, and returns the identifier
that it has associated with semkey.

semkey is  an identifier  that your  application generates to  identify its
semaphores.

number gives the of semaphores you want shmget() to create.

flag can be bitwise OR'd to include the following constants:

IPC_ALLOC This process already has a set of semaphores; please fetch it.

IPC_CREAT If this process does not  have a set of semaphores, please create
          one.

IPC_EXCL  Fail if this process already has a set of semaphores.

IPC_NOWAIT
          Fail if the process must wait to obtain a set of semaphores.

When  it creates  a set  of  semaphores, semget()  also creates  a copy  of
structure  semid_ds, which  the  header file  <sys/sem.h> defines  as
follows:

struct semid_ds {
     struct ipc_perm sem_perm;/* operation permission struct */
     struct sem *sem_base;  /* pointer to first semaphore in set */
     unsigned short sem_nsems;/* # of semaphores in set */
     time_t sem_otime;      /* last semop time */
     time_t sem_ctime;      /* last change time */
};

Field  sem_base points  the  semaphores themselves.   Each  semaphore is  a
structure  of type  sem,  which header  file  <sys/sem.h> defines  as
follows:

struct sem {
     unsigned short semval; /* semaphore text map address */
     short sempid;          /* pid of last operation */
     unsigned short semncnt;/* # awaiting semval > cval */
     unsigned short semzcnt;/* # awaiting semval = 0 */
};

Field  sem_perm  is  a  structure  of  type  ipc_perm,  which  header  file
<sys/ipc.h> defines as follows:

struct ipc_perm {
     unsigned short uid;    /* owner's user id */
     unsigned short gid;    /* owner's group id */
     unsigned short cuid;   /* creator's user id */
     unsigned short cgid;   /* creator's group id */
     unsigned short mode;   /* access modes */
     unsigned short seq;    /* slot usage sequence number */
     key_t key;             /* key */
};

semget() initializes semid_ds as follows:

-> It  sets  the  fields  sem_perm.cuid, sem_perm.uid,  sem_perm.cgid,  and
   sem_perm.gid to, respectively,  the effective user and group identifiers
   of the calling process.

-> It sets  the low-order nine bits of sem_perm.mode  to the low-order nine
   bits of  flag. These nine bits define access  permissions: the top three
   bits  give the  owner's access permissions  (read, write,  execute), the
   middle three  bits the  owning group's  access permissions, and  the low
   three bits access permissions for others.

-> It  sets sem_nsems  to number.  This gives the  number of  semaphores to
   which sem_base points.

-> It  sets field  sem_otime to  zero, and field  sem_ctime to  the current
   time.

semget() fails if any of the following are true:

-> number is less  than one and the set of  semaphores identified by semkey
   does not exist.  semget() sets errno to EINVAL.

-> number exceeds the system-imposed limit (EINVAL).

-> A semaphore  identifier exists for semkey,  but permission, as specified
   flag's low-order nine bits, is not granted (EACCES).

-> A semaphore  identifier exists for semkey, but  the number of semaphores
   in its set is less than number, and number does not equal zero (EINVAL).

-> A  semaphore  identifier  does not  exist  for  semkey  and (flag  &
   IPC_CREAT) is false (ENOENT).

-> semget() tried to create a set  of semaphores, but could not because the
   maximum number of sets allowable by the system always exists (ENOSPC).

-> A semaphore identifier already  exists for semkey but flag requests that
   semget() create an exclusive set for it -- i.e.

       ( (flag & IPC_CREAT) && (flag & IPC_EXCL) )

   is true (EEXIST).

If all goes well, semget()  returns a semaphore identifier, which is always
a  non-negative integer.   Otherwise, it  returns -1 and  sets errno  to an
appropriate value.

Files

/usr/include/sys/ipc.h
/usr/include/sys/sem.h

See Also

ftok(),
ipcrm,
ipcs,
libc,
libsocket,
semctl(),
semop()

Notes

Prior to  release 4.2, COHERENT  implemented semaphores through  the driver
sem.  In release  4.2, and  subsequent  releases, COHERENT  has implemented
semaphores as  a set of  functions that conform  in large part  to the UNIX
System-V standard.

The  kernel variables  SEMMNI  and SHMMNS  set,  respectively, the  maximum
number of  identifiers that  can exist  at any given  time and  the maximum
number of  semaphores that a set can hold.   Daredevil system operators who
have large  amounts of memory  at their disposal  may wish to  change these
variables to increase the system-defined  limits.  For details on how to do
so, see the Lexicon entry mtune.

© 2012 by Stephen A. Ness