DosCreateMuxWaitSem
From EDM2
DosCreateMuxWaitSem creates a private or shared MuxWait semaphore. The usage count is incremented to 1. The process creating the semaphore does not need to open it also.
Contents
Syntax
rc = DosCreateMuxWaitSem( pszSemaphoreName, phmuxSemaphore, ulNumberOfRecords, pSemaphoreRecord, ulfAttributes );
Parameters
- PSZ pszSemaphoreName (input)
- This is a pointer to the null-terminated string containing the semaphore name. Any named semaphore is considered shared. An unnamed semaphore will be created with pszSemaphoreName set to NULL. The name of a semaphore must be prefixed by \SEM32\, cannot be longer than 255 characters and must conform to the naming conventions of the file system.
- PHMUX phmuxSemaphore (output)
- This is a pointer to the HMUX that will get the handle to the new semaphore.
- ULONG ulNumberOfRecords (input)
- This is the number of records that are pointed to by pSemaphoreRecord. 64 is the maximum number of records allowable in a muxwait list.
- PSEMRECORD pSemaphoreRecord (input)
- This points to an array of SEMRECORD structures that are to be added to the muxwait list.
- ULONG ulfAttributes (input)
- This contains the attribute flags relevant to the creation of the semaphore. As of this writing three values may be set for ulAttributeFlags, they are
DC_SEM_SHARED, DCMW_WAIT_ANY and DCMW_WAIT_ALL.
- ulAttributeFlags is checked for DC_SEM_SHARED value only if pszSemaphoreName is NULL. If ulAttributeFlags equals DC_SEM_SHARED then the semaphore is considered an unnamed, shared semaphore.
- DCMW_WAIT_ANY indicates the semaphore is to unblock if any of the semaphores in the muxwait list post (event semaphore) or release (mutex semaphore).
- DCMW_WAIT_ALL indicates the semaphore is to unblock only if all of the semaphores in the muxwait list post (event semaphore) or release (mutex semaphore).
Returns
APIRET rc
The following values can be returned
0 | NO_ERROR | Operation was successful. |
6 | ERROR_INVALID_HANDLE | Error, The calling process must first have access to the shared semaphore in question before adding it to the muxwait list |
8 | ERROR_NOT_ENOUGH_MEMORY | Error, Memory limit has been exceeded |
87 | ERROR_INVALID_PARAMETER | Error, Unrecognized parameter |
100 | ERROR_TOO_MANY_SEMAPHORES | Error, The value in ulNumberOfRecords cannot exceed 64 |
105 | ERROR_SEM_OWNER_DIED | Error, The owner of a semaphore in the muxwait list has died before releasing it |
123 | ERROR_INVALID_NAME | Error, Name in pszSemaphoreName was rejected by file system |
284 | ERROR_DUPLICATE_HANDLE | Error, The muxwait list pointed to by pSemaphoreRecord contains duplicate entries |
285 | ERROR_DUPLICATE_NAME | Error, Name in pszSemaphoreName is in use |
290 | ERROR_TOO_MANY_HANDLES | Error, System limit of 65536 semaphores has been exceeded |
292 | ERROR_WRONG_TYPE | Error, One or more entries in the muxwait list pointed to by pSemaphoreRecord is of the wrong type, MuxWait semaphores may not be added to a muxwait list, if the MuxWait semaphore is shared then only shared semaphores may be added to the list, If the MuxWait semaphore is private than the list may contain both shared and private semaphores |
Sample Code
#define INCL_DOSSEMAPHORES #include <os2.h> #include <string.h> PUCHAR SemName; /* Pointer to the Semaphore Name */ PHMUX phmuxMySemaphore; /* pointer to my new semaphore handle */ ULONG ulAttribs= 0; /* Attribute flags, not used in this case */ SEMRECORD SemRecord; /* Record containing info about the sem I want to add to MySemaphore's list */ int main(){ /* put the semaphore name in SemName */ strcpy(SemName,"\\SEM32\\MySem"); /* SemRecord is filled with appropriate information about the semaphore I wish to add to hmuxMySemaphore's list */ rc = DosCreateMuxWaitSem( SemName, phmuxMySemaphore, 1, /* 1 record to add */ &SemRecord, ulAttribs); if (rc != 0){ /* We got an error to take care of. */ } }