Semaphore Set Functions

A semaphore is a synchronization mechanism similar to a mutex or a machine interface (MI) lock. It can be used to control access to shared resources, or used to notify other threads of the availability of resources. It differs from a mutex in the following ways:

Thus, a semaphore can be used as a resource counter or as a lock.

A process gets a semaphore set identifier by calling the semget() function. Depending on the key and semflg parameters passed in, either a new semaphore set is created or an existing semaphore set is accessed. When a new semaphore set is created, a data structure is also created to contain information about the semaphore set. This structure is defined in the <sys/sem.h> header file as follows:

typedef struct semid_ds {
  struct ipc_perm sem_perm;  /* Permissions */
  unsigned short  sem_nsems; /* Number of semaphores in set */
#if ((defined _64_BIT_TIME) && (__OS400_TGTVRM__ >= 740)) 
  time64_t        sem_otime; /* Time of last semop() */       
  time64_t        sem_ctime; /* Time of last change by semctl_time64() */
#else                                                    
  time_t          sem_otime; /* Time of last semop() */
  time_t          sem_ctime; /* Time of last change by semctl() */
#endif                                                   
} semtablentry_t;

#if (__OS400_TGTVRM__ >= 740)                             
/* Semaphore set information */                       
typedef struct semid_ds_time64 {                        
  struct ipc_perm sem_perm;  /* Permissions */        
  unsigned short  sem_nsems; /* Number of semaphores in set */    
  time64_t        sem_otime; /* Time of last semop() */     
  time64_t        sem_ctime; /* Time of last change by semctl_time64() */
} semtablentry_time64_t;                                    
#endif

A thread performs operations on one or more of the semaphores in a set by calling the semop() function. The following parameters are passed in:

The sembuf structure is defined in the <sys/sem.h> header file as follows:

struct sembuf {
     unsigned short  sem_num; /* Semaphore number    */
     short           sem_op;  /* Semaphore operation */
     short           sem_flg; /* Operation flags     */
};

The operation performed on a semaphore is specified by the sem_op field, which can be positive, negative, or zero:

The sem_flg value specifies whether or not the thread is willing to wait, and also whether or not the thread wants the system to keep a semaphore adjustment value for the semaphore.

Semaphore waits are visible from the Work with Active Jobs display. A thread waiting on a semaphore in a semaphore set appears to be in a semaphore wait state (SEMW) on the Work with Threads display (requested using the WRKJOB command and taking option 20). Displaying the call stack of the thread shows the semop() function near the bottom of the stack.

A thread removes a semaphore set ID by calling the semctl() function. The thread also can use the semctl() function to change the data structure values associated with the semaphore set ID or to retrieve the data structure values associated with the semaphore set ID. The following parameters are passed in:

In addition, the semctl() function can perform various other control operations on a specific semaphore within a set, or on an entire semaphore set:


Semaphore Set Differences and Restrictions

IBM® i semaphore sets differ from the definition in the Single UNIX® Specification in the following ways:

The semaphore set functions are:

See also IPC Key Generation Functions for additional semaphore set functions.


[ Back to top | UNIX-Type APIs | APIs by category ]