Using semaphores

Before semaphores can be used (operated on or controlled) a uniquely identified data structure and semaphore set (array) must be created. The unique identifier is called the semaphore set identifier (semid); it is used to identify or refer to a particular data structure and semaphore set. This identifier is accessible by any process in the system, subject to normal access restrictions.

The semaphore set contains a predefined number of structures in an array, one structure for each semaphore in the set. The number of semaphores (nsems) in a semaphore set is user selectable. The following members are in each structure within a semaphore set:

• semaphore value

• PID performing last operation

• number of processes waiting for the semaphore value to become greater than its current value

• number of processes waiting for the semaphore value to equal zero

There is one associated data structure for the uniquely identified semaphore set. This data structure contains the following information related to the semaphore set:

• operation permissions data (operation permissions structure)

• pointer to first semaphore in the set (array)

• number of semaphores in the set

• last semaphore operation time

• last semaphore change time

The definition for the semaphore set (array member) sem is as follows:

   struct sem
   {
           ushort  semval;         /* semaphore value */
           pid_t   sempid;         /* pid of last operation */
           ushort  semncnt;        /* # awaiting semval > cval */
           ushort  semzcnt;        /* # awaiting semval = 0 */
   };

Likewise, the definition for the associated semaphore data structure semid_ds contains the following members:

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

The C programming language data structure definition for the semaphore set (array member) and for the semid_ds data structure are located in the sys/sem.h header file.

Note that the sem_perm member of this structure uses ipc_perm as a template. ``ipc_perm data structure'' breaks out the operation permissions data structure.

The ipc_perm data structure is the same for all IPC facilities; it is located in the sys/ipc.h header file and is shown in the ``Messages''.

The semget system call is used to perform two tasks:

• to get a new semaphore set identifier and create an associated data structure and semaphore set for it

• to return an existing semaphore set identifier that already has an associated data structure and semaphore set

The task performed is determined by the value of the key argument passed to the semget system call. For the first task, if the key is not already in use for an existing semid and the IPC_CREAT flag is set, a new semid is returned with an associated data structure and semaphore set created for it provided no system tunable parameter would be exceeded.

There is also a provision for specifying a key of value zero (0), which is known as the private key (IPC_PRIVATE). When this key is specified, a new identifier is always returned with an associated data structure and semaphore set created for it, unless a system-tunable parameter would be exceeded. The ipcs command will show the key field for the semid as all zeros.

When performing the first task, the process which calls semget becomes the owner/creator, and the associated data structure is initialized accordingly. Remember, ownership can be changed, but the creating process always remains the creator (see ``Controlling semaphores''). The creator of the semaphore set also determines the initial operation permissions for the facility.

For the second task, if a semaphore set identifier exists for the key specified, the value of the existing identifier is returned. If you do not want to have an existing semaphore set identifier returned, a control command (IPC_EXCL) can be specified (set) in the semflg argument passed to the system call. The system call will fail if it is passed a value for the number of semaphores (nsems) that is greater than the number actually in the set; if you do not know how many semaphores are in the set, use 0 for nsems (see ``Using semget'' for how to use this system call).

Once a uniquely identified semaphore set and data structure are created, semop (semaphore operations) and semctl (semaphore control) can be used.

Semaphore operations consist of incrementing, decrementing, and testing for zero. The semop system call is used to perform these operations (see ``Operations on semaphores'' for details of the semop system call.

The semctl system call permits you to control the semaphore facility in the following ways:

• by returning the value of a semaphore (GETVAL)

• by setting the value of a semaphore (SETVAL)

• by returning the PID of the last process performing an operation on a semaphore set (GETPID)

• by returning the number of processes waiting for a semaphore value to become greater than its current value (GETNCNT)

• by returning the number of processes waiting for a semaphore value to equal zero (GETZCNT)

• by getting all semaphore values in a set and placing them in an array in user memory (GETALL)

• by setting all semaphore values in a semaphore set from an array of values in user memory (SETALL)

• by retrieving the data structure associated with a semaphore set (IPC_STAT)

• by changing operation permissions for a semaphore set (IPC_SET)

• by removing a particular semaphore set identifier from the UNIX operating system along with its associated data structure and semaphore set (IPC_RMID)