DosCreateEventSem: Difference between revisions
m Ak120 moved page OS2 API:CPI:DosCreateEventSem to DosCreateEventSem |
mNo edit summary |
||
| (2 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
DosCreateEventSem creates a system event semaphore. The semaphore may be either private or shared and is accessible by all threads of the calling process. | |||
DosCreateEventSem creates a system event semaphore. The semaphore may be either private or shared and is | |||
==Syntax== | ==Syntax== | ||
| Line 8: | Line 5: | ||
==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. | |||
;PHEV phevSemaphore (output):This is a pointer to the HEV that will get the handle to the new semaphore. | |||
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. | ;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. | |||
This is a pointer to the HEV 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 | |||
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== | ==Sample Code== | ||
<PRE> | <PRE> | ||
| Line 67: | Line 45: | ||
/* The semaphore may be accessed via the phevMySemaphore handle */ | /* The semaphore may be accessed via the phevMySemaphore handle */ | ||
} | } | ||
</PRE> | </PRE> | ||
==See Also== | ==See Also== | ||
* [[ | *[[DosCloseEventSem]] | ||
*[[DosOpenEventSem]] | |||
*[[DosPostEventSem]] | |||
*[[DosQueryEventSem]] | |||
*[[DosResetEventSem]] | |||
*[[DosWaitEventSem]] | |||
[[Category: | [[Category:Dos]] | ||
Latest revision as of 10:15, 12 October 2018
DosCreateEventSem creates a system event semaphore. The semaphore may be either private or shared and is accessible by all threads of the calling process.
Syntax
rc = DosCreateEventSem( pszSemaphoreName, phevSemaphore, 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.
- PHEV phevSemaphore (output)
- This is a pointer to the HEV 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 */
PHEV phevMySemaphore; /* 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 = DosCreateEventSem(SemName, phevMySemaphore, ulAttribs, f32Owned);
if (rc != 0)
{
/* We got an error to take care of. */
}
else
{
/* creation was successful */
/* The semaphore may be accessed via the phevMySemaphore handle */
}