DosCreateMutexSem
From EDM2
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.
Contents
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 */ }