Difference between revisions of "DosCreateMutexSem"
From EDM2
m (Ak120 moved page OS2 API:CPI:DosCreateMutexSem to DosCreateMutexSem) |
|||
Line 1: | Line 1: | ||
− | + | 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'', | rc = DosCreateMutexSem( ''pszSemaphoreName'', | ||
''phmtxSemaphore'', | ''phmtxSemaphore'', | ||
''ulAttributeFlags'', | ''ulAttributeFlags'', | ||
''f32InitialState'' ); | ''f32InitialState'' ); | ||
− | |||
=== Parameters === | === 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. | |
− | This is a pointer to the null-terminated string containing the semaphore | + | ;PHMTX ''phmtxSemaphore'' (output):This is a pointer to the HMTX that will get the handle to the new semaphore. |
− | name. | + | ;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 |
− | be created with ''pszSemaphoreName'' set to NULL. | + | '''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. |
− | be prefixed by \SEM32\, cannot be longer than 255 characters and | + | ;BOOL32 ''f32InitialState'' (input):This boolean flag marks the initial state of the semaphore. |
− | must conform to the naming conventions of the file system. | + | |
− | + | ||
− | + | ||
− | + | ||
− | This is a pointer to the HMTX that will get the handle to the new semaphore. | + | |
− | + | ||
− | + | ||
− | + | ||
− | 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. | + | |
− | + | ||
− | + | ||
− | + | ||
− | 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 '''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. | * Setting '''FALSE''' (0x00000000) makes the initial state of the semaphore unowned and threads waiting on the semaphore will not block. | ||
− | |||
=== Returns === | === Returns === | ||
− | + | APIRET rc | |
− | + | ||
The following values can be returned | The following values can be returned | ||
− | |||
{| border="1" | {| border="1" | ||
|- | |- | ||
Line 66: | Line 45: | ||
|ERROR_TOO_MANY_HANDLES | |ERROR_TOO_MANY_HANDLES | ||
|Error, System limit of 65536 semaphores has been exceeded | |Error, System limit of 65536 semaphores has been exceeded | ||
− | |} | + | |} |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
=== Sample Code === | === Sample Code === | ||
<PRE> | <PRE> | ||
#define INCL_DOSSEMAPHORES | #define INCL_DOSSEMAPHORES | ||
− | #include | + | #include <os2.h> |
− | UCHAR SemName; /* Pointer to the Semaphore Name */ | + | UCHAR SemName; /* Pointer to the Semaphore Name */ |
PHMTX phmtxMySemaphore; /* pointer to my new semaphore handle */ | PHMTX phmtxMySemaphore; /* pointer to my new semaphore handle */ | ||
ULONG ulAttribs= 0; /* Attribute flags, not used in this case */ | ULONG ulAttribs= 0; /* Attribute flags, not used in this case */ | ||
Line 109: | Line 74: | ||
=== See Also === | === See Also === | ||
− | [[ | + | *[[DosCloseMutexSem]] |
− | [[ | + | *[[DosOpenMutexSem]] |
− | [[ | + | *[[DosQueryMutexSem]] |
− | [[ | + | *[[DosReleaseMutexSem]] |
− | [[ | + | *[[DosRequestMutexSem]] |
− | [[Category: | + | [[Category:Dos]] |
Revision as of 04:17, 9 January 2017
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 */ }