Pointer Based Services

The pointer based services consist of named and unnamed semaphores. The named and unnamed semaphores on i5/OS^(R) differ from the other IPC mechanisms in that they do not have an IPC identifier associated with them. Instead, pointers to the semaphore are used to operate on the semaphore. Before using a semaphore, a process must obtain a pointer to the semaphore. Unlike a semaphore set, a named or unnamed semaphore refers to a single semaphore only. A semaphore contains a value, a maximum value, and a title.

There are two types of semaphores: named semaphores and unnamed semaphores. Once a semaphore is created and a pointer to the semaphore is obtained, the same operations are used to manipulate the values of both types of semaphores. Like the semaphores in a semaphore set, a named or unnamed semaphore has a nonzero value. A semaphore can be used as a resource counter or as a lock. A thread decrements a semaphore to obtain one or more associated resources, and increments the semaphore to release the resource. A semaphore also has a maximum value associated with it. An attempt to increment the value of a semaphore above its maximum value results in an error.

Besides a value, named and unnamed semaphores contain a maximum value and a title. The maximum value sets the highest value that the semaphore value may obtain. The title is a null-terminated string with a maximum size of 16 characters that are associated with the semaphore and may be used to contain debugging information. The titles associated with named and unnamed semaphores may be obtained by using the QP0ZOLIP() API.

A process obtains a pointer to a named semaphore by calling the sem_open() or sem_open_np() functions. These functions find the semaphore associated with a name. The name is a character string, interpreted in the CCSID of the job. The name may be structured so that it looks like a pathname. This name, however, has no relationship to any file system. If the semaphore exists and the process has permission to use the semaphore, then the system allocates memory for the semaphore and returns a pointer to the caller. If the semaphore does not exist, it will be created if the appropriate flags are set. When a new named semaphore is created, the permissions of the semaphore are set using the information provided by the mode parameter. These permissions are the same as those used by the identifier- based IPC services. The sem_open_np() function permits the caller to set the maximum value and title of a semaphore when creating a named semaphore. When a process is finished using a named semaphore, it should call sem_close() to close the semaphore. The semaphore is also explicitly closed when a process terminates. When a named semaphore will no longer be needed, it can be removed from the system using sem_unlink().

A process obtains a pointer to an unnamed semaphore calling the sem_init() or sem_init_np() functions. These functions initialize a semaphore at the specified memory location. The sem_init_np() function permits the caller to set the maximum value and title of a unnamed semaphore when it is created. When a process is finished using an unnamed semaphore, it should call sem_destroy() to destroy the semaphore and release system resources associated with that semaphore.

A process decrements by one the value of a semaphore using the sem_wait() and sem_wait_np() functions. If the value of the semaphore is currently zero, then the thread is blocked until the value of the semaphore is incremented or until the time specified on the sem_wait_np() has expired. The sem_trywait() call may be used to decrement the value of the semaphore if it is greater than zero. If the current value of the semaphore is zero, then sem_trywait() will return an error. The sem_post()and sem_post_np()functions are used to increment the value of a semaphore. After the value of the semaphore is incremented, it may be decremented immediately by threads that have blocked trying to decrement the semaphore.

Named and unnamed semaphore waits are visible from the Work with Active Jobs display. A thread waiting on a named or unnamed semaphore will be in a semaphore wait state (SEMW).

The sem_getvalue()function returns the value of the semaphore if the value is greater than or equal to zero. If there are threads waiting on the semaphore, sem_getvalue() returns a negative number whose absolute value is the number of threads waiting on the semaphore.

For details on the semaphore functions, see the following:

• QlgSem_open() (Open Named Semaphore (using NLS-enabled path name)) opens a named semaphore and returns a semaphore pointer that may be used on subsequent calls to sem_post(), sem_post_np(), sem_wait(), sem_wait_np(), sem_trywait(), sem_getvalue(), and sem_close().
• QlgSem_open_np() (Open Named Semaphore with Maximum Value (using NLS-enabled path name)) opens a named semaphore and returns a semaphore pointer that may be used on subsequent calls to sem_post(), sem_post_np(), sem_wait(), sem_wait_np(), sem_trywait(), sem_getvalue(), and sem_close().
• QlgSem_unlink() (Unlink Named Semaphore (using NLS-enabled path name)) unlinks a named semaphore.
• sem_close() (Close Named Semaphore) closes a named semaphore that was previously opened by a thread of the current process using sem_open() or sem_open_np().
• sem_destroy() (Destroy Unnamed Semaphore) destroys an unnamed semaphore that was previously initialized using sem_init() or sem_init_np().
• sem_getvalue() (Get Semaphore Value) retrieves the value of a named or unnamed semaphore.
• sem_init() (Initialize Unnamed Semaphore) initializes an unnamed semaphore and sets its initial value.
• sem_init_np() (Initialize Unnamed Semaphore with Maximum Value) initializes an unnamed semaphore and sets its initial value.
• sem_open() (Open Named Semaphore) opens a named semaphore, returning a semaphore pointer that may be used on subsequent calls to sem_post(), sem_post_np(), sem_wait(), sem_wait_np(), sem_trywait(), sem_getvalue(), and sem_close().
• sem_open_np() (Open Named Semaphore with Maximum Value) opens a named semaphore, returning a semaphore pointer that may be used on subsequent calls to sem_post(), sem_post_np(), sem_wait(), sem_wait_np(), sem_trywait(), sem_getvalue(), and sem_close().
• sem_post() (Post to Semaphore) posts to a semaphore, incrementing its value by one.
• sem_post_np() (Post Value to Semaphore) posts to a semaphore, incrementing its value by the increment specified in the options parameter.
• sem_trywait() (Try to Decrement Semaphore) attempts to decrement the value of the semaphore.
• sem_unlink() (Unlink Named Semaphore) unlinks a named semaphore.
• sem_wait() (Wait for Semaphore) decrements by one the value of the semaphore.
• sem_wait_np() (Wait for Semaphore with Timeout) attempts to decrement by one the value of the semaphore.