Processes other than the semaphore-creating process must use DosOpenMuxWaitSem to gain access to the muxwait semaphore before they can use the semaphore in any other muxwait semaphore function. All of the threads that belong to the process that creates the muxwait semaphore have immediate access to the semaphore.
The following code fragment opens a system muxwait semaphore.
#define INCL_DOSSEMAPHORES /* Semaphore values */
#include <os2.h>
#include <stdio.h>
#include <string.h>
UCHAR ucName[40]; /* Semaphore name */
HMUX hmux; /* Muxwait semaphore handle */
APIRET ulrc; /* Return code */
strcpy(ucName,
"\\SEM32\\MUXWAIT1"); /* Name of the system muxwait semaphore */
ulrc = DosOpenMuxWaitSem(ucName,
&hmux);
if (ulrc != 0) {
printf("DosOpenMuxWaitSem error: return code = %ld",
ulrc);
return;
}
On successful return, hmux contains the handle of the system muxwait semaphore.
Opening a muxwait semaphore does not open the semaphores in its muxwait list. A process must open each of the semaphores included in a muxwait semaphore before it opens the muxwait semaphore. Otherwise, DosOpenMuxWaitSem returns the ERROR_INVALID_HANDLE error value to the calling function.
Access to semaphores is on a per-process basis. Therefore, a semaphore that has been opened by one thread in a process is open to all other threads in that process as well.
Note that DosOpenMuxWaitSem merely provides access to a muxwait semaphore. In order to wait for a muxwait semaphore to clear, a thread must call DosWaitMuxWaitSem.
When a process no longer requires access to a muxwait semaphore, it closes the semaphore by calling DosCloseMuxWaitSem. However, if a process ends without closing an open semaphore, the semaphore is closed by OS/2.
Each call to DosOpenMuxWaitSem increments the usage count of the semaphore. This count is initialized to 1 when the semaphore is created and is decremented by each call to DosCloseMuxWaitSem. When the usage count reaches 0, the semaphore is deleted by OS/2.
Calls to DosOpenMuxWaitSem and DosCloseMuxWaitSem can be nested, but the usage count for a semaphore cannot exceed 65535. If an attempt is made to exceed this number, ERROR_TOO_MANY_OPENS is returned.
Even if the owner of a mutex semaphore in a muxwait-semaphore list has ended without releasing the semaphore, the muxwait semaphore is still opened. Subsequent calls to the muxwait semaphore will return ERROR_SEM_OWNER_DIED. But because the process has opened the semaphore, it can then call DosQueryMuxWaitSem to identify all the mutex semaphores in the muxwait list. Next, the process can call DosQueryMutexSem for each mutex semaphore in the list to find out which ones are in the Owner Died state. Each mutex semaphore that returns ERROR_SEM_OWNER_DIED from the query should be closed by calling DosCloseMutexSem. Also, because semaphore handles can be reused, the mutex semaphores that are closed should be deleted from the muxwait-semaphore list by calling DosDeleteMuxWaitSem.