Jump to content

DosCreateMutexSem: Difference between revisions

From EDM2
← Older editNewer edit →
Ak120 (talk | contribs)
35,883 edits
Ak120 (talk | contribs)
35,883 edits
No edit summary
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 ===
=== Syntax ===
  rc = DosCreateMutexSem( ''pszSemaphoreName'',  
  rc = DosCreateMutexSem( ''pszSemaphoreName'',  
                         ''phmtxSemaphore'',  
                         ''phmtxSemaphore'',  
                         ''ulAttributeFlags'',  
                         ''ulAttributeFlags'',  
                         ''f32InitialState'' );
                         ''f32InitialState'' );


=== Parameters ===
=== Parameters ===
'''PSZ ''pszSemaphoreName'' (input)'''
;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. Any named semaphore is considered shared. An unnamed semaphore will  
;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. The name of a semaphore must
'''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.
 
'''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 '''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
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
|}
|}
=== Include Info ===
 
#define INCL_DOSSEMAPHORES
#include <os2.h>
 
 
=== Usage Explanation ===
 
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.
 
 
=== Relevant Structures ===
=== Gotchas ===
   
   
=== 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 ===
[[OS2 API:CPI:DosCloseMutexSem|DosCloseMutexSem]],
*[[DosCloseMutexSem]]
[[OS2 API:CPI:DosOpenMutexSem|DosOpenMutexSem]],
*[[DosOpenMutexSem]]
[[OS2 API:CPI:DosQueryMutexSem|DosQueryMutexSem]],
*[[DosQueryMutexSem]]
[[OS2 API:CPI:DosReleaseMutexSem|DosReleaseMutexSem]],
*[[DosReleaseMutexSem]]
[[OS2 API:CPI:DosRequestMutexSem|DosRequestMutexSem]]  
*[[DosRequestMutexSem]]  


[[Category:The OS/2 API Project]]
[[Category:Dos]]

Revision as of 06: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.

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

See Also

Retrieved from "https://www.edm2.com/index.php?title=DosCreateMutexSem&oldid=39713"