Creates or opens a semaphore.

HANDLE RtCreateSemaphore(
    LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
    LONG lInitialCount,
    LONG lMaximumCount,
    LPCTSTR lpName
);

lpSemaphoreAttributes

Ignored. Set to NULL

lInitialCount

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.

lMaximumCount

Specifies the maximum count for the semaphore object. This value must be greater than zero.

lpName

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:

NULL

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.

Remarks

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

Success.

Handle to existing object and ERROR_ALREADY_EXISTS

The semaphore object existed before the function call.

NULL

Failure. For extended error information, see the Windows' GetLastError function.

Requirements

Notes

• This function operates in the Windows portion of your application.
• The iwin32 API also includes an RtCreateSemaphore function that operates in the real-time portion of your application.

See Also

RtCloseHandle, RtReleaseSemaphore, iwin32x API, iwin32 Overview