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
rc = 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 */
}