INtime SDK Help
RtCreateSemaphore (iwin32x)
INtime SDK v7 > About INtime > Alternate APIs > iwin32 API > iwin32x API > RtCreateSemaphore (iwin32x)

Creates or opens a semaphore.

HANDLE RtCreateSemaphore(
    LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
    LONG lInitialCount,
    LONG lMaximumCount,
    LPCTSTR lpName
Ignored. Set to NULL
Specifies an initial count for the semaphore object. This value must be greater than or equal to zero and less than or equal to lMaximumCount. A semaphore's state is signaled when its count is greater than zero, and nonsignaled when zero. The count decreases by one whenever a wait function releases a thread that was waiting for the semaphore. To increase the count by a specified amount, call RtReleaseSemaphore.
Specifies the maximum count for the semaphore object. This value must be greater than zero.
Pointer to a null-terminated string that specifies the semaphore object. The name is limited to MAX_PATH characters and can contain any character except the backslash path-separator character (\). Name comparison is case sensitive. Values include:
The mutex semaphore object is created without a name.
Matches an existing named semaphore object
Ignores the lInitialCount and lMaximumCount parameters because they were already set by the creation process.
Matches the name of an existing event, mutex, or shared memory object
The function fails and the Windows' GetLastError function returns ERROR_INVALID_HANDLE. This occurs because these objects share the same name space.


You can use the handle returned by CreateSemaphore in any function that requires a handle to a semaphore object.

The state of a semaphore object is signaled when its count is greater than zero, and nonsignaled when its count is equal to zero. The lInitialCount parameter specifies the initial count. Each time a waiting thread is released because of the semaphore's signaled state, the semaphore count decreases by one. To increment a semaphore's count by a specified amount, use ReleaseSemphore. The count can never be less than zero or greater than the value specified in the lMaximumCount parameter.

Multiple processes can have handles of the same semaphore object, enabling use of the object for interprocess synchronization. To share an object, a process can specify the name of a semaphore object in a call to CreateSemaphore.

To close the handle, use RtCloseHandle. When the process terminates, the system automatically closes the handle. When its last handle closes, the semaphore object is destroyed.

RtCreateSemaphore can also be used within the real-time portion of your application to create an iwin32 semaphore.

Return Values

Handle to a semaphore object
Handle to existing object and ERROR_ALREADY_EXISTS
The semaphore object existed before the function call.
Failure. For extended error information, see the Windows' GetLastError function.


Versions Defined in Include Link to
INtime 3.0 intime/nt/include/iwin32x.h iwin32x.h iwin32x.lib


See Also

RtCloseHandle, RtReleaseSemaphore, iwin32x API, iwin32 Overview