Creates a named or unnamed semaphore object.

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

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

Parameters

lpSemaphoreAttributes

Ignored. Must be 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 ReleaseSemaphore.

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 GetLastError 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 CloseHandle. 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 from a Windows 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 GetLastError.

Requirements

Notes

• In the iwin32 API, CreateSemaphore and RtCreateSemaphore are synonyms.
• This function operates in the real-time portion of your application.
• The iwin32x API also includes an RtCreateSemaphore function that operates in the Windows portion of your application.

See Also

CloseHandle, ReleaseSemaphore, iwin32 API, iwin32 Overview