DosCreateMutexSem
DosCreateMutexSem creates a system mutual exclusion (mutex) semaphore. The semaphore may be either private or shared and is accessible by all threads of the calling process.
Syntax
DosCreateMutexSem( pszSemaphoreName,
phmtxSemaphore,
ulAttributeFlags,
f32InitialState )
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.
- PHMTX phmtxSemaphore (output)
- This is a pointer to the HMTX that will get the handle to the new semaphore.
- ULONG ulAttributeFlags (input)
- This contains the attribute flags relevant to the creation of the semaphore. As of this writing only one value may be set for ulAttributeFlags, it is DC_SEM_SHARED. ulAttributeFlags is checked for this value only if pszSemaphoreName is NULL. If ulAttributeFlags equals DC_SEM_SHARED then the semaphore is considered an unnamed, shared semaphore.
- BOOL32 f32InitialState (input)
- This boolean flag marks the initial state of the semaphore.
- Setting TRUE (0x00000001) makes the initial state of the semaphore owned and threads waiting on the semaphore will block.
- Setting FALSE (0x00000000) makes the initial state of the semaphore unowned and threads waiting on the semaphore will not block.
Returns
- APIRET rc
- The following values can be returned:
- 0 NO_ERROR - Semaphore created successfully
- 8 ERROR_NOT_ENOUGH_MEMORY - Error, Memory limit has been exceeded
- 87 ERROR_INVALID_PARAMETER - Error, Unrecognized parameter
- 123 ERROR_INVALID_NAME - Error, Name in pszSemaphoreName was rejected by file system
- 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
Sample Code
#define INCL_DOSSEMAPHORES
#include <os2.h>
UCHAR SemName; /* Pointer to the Semaphore Name */
PHMTX phmtxMySemaphore; /* pointer to my new semaphore handle */
ULONG ulAttribs= 0; /* Attribute flags, not used in this case */
BOOL32 f32Owned= TRUE; /* initial state of the semaphore, owned */
/* put the semaphore name in SemName */
strcpy(SemName,"\\SEM32\\MySem");
rc = DosCreateMutexSem(SemName, phmtxMySemaphore, ulAttribs, f32Owned);
if (rc != 0)
{
/* We got an error to take care of. */
}
else
{
/* creation was successful */
/* The semaphore may be accessed via the phmtxMySemaphore handle */
}