The CreateSemaphore function creates a semaphore object and sets its initial count. A semaphore is a synchronization object that maintains a count for a specified number of clients. When a client requests access to the semaphore, its count is decremented. When a client releases the semaphore, its count is incremented.
HANDLE CreateSemaphoreA(
[in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
[in] LONG lInitialCount,
[in] LONG lMaximumCount,
[in, optional] LPCSTR lpName
);
HANDLE CreateSemaphoreW(
[in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
[in] LONG lInitialCount,
[in] LONG lMaximumCount,
[in, optional] LPCWSTR lpName
);
The CreateSemaphore function is the ANSI version of the function. The CreateSemaphoreW function is the Unicode version of the function.
| Parameter | Description |
|---|---|
lpSemaphoreAttributes |
A pointer to a SECURITY_ATTRIBUTES structure that specifies the security attributes of the semaphore. If this parameter is NULL, the semaphore gets a default security descriptor.
|
lInitialCount |
The initial count for the semaphore object. This value must be greater than or equal to zero and less than or equal to lMaximumCount.
|
lMaximumCount |
The maximum count for the semaphore object. This value must be greater than zero. |
lpName |
A pointer to a null-terminated string that specifies the name of the semaphore object. The name is limited to MAX_PATH characters.
If lpName is NULL, the semaphore object is created without a name.
If an object with the same name already exists, the function fails and GetLastError returns ERROR_ALREADY_EXISTS.
|
If the function succeeds, the return value is a handle to the newly created semaphore object. The handle has the SYNCHRONIZE access right and is valid until the calling process has closed it. If the semaphore was successfully created and already existed, the return value is a handle to the existing semaphore object and GetLastError returns ERROR_ALREADY_EXISTS.
If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Semaphores are useful for protecting a pool of resources or for controlling access to a shared resource that can only be used by a limited number of threads at a time.
To use a semaphore, threads call WaitForSingleObject or WaitForMultipleObjects to request access. If the semaphore's count is greater than zero, the call returns immediately, and the count is decremented. If the semaphore's count is zero, the thread enters the wait state until the count becomes greater than zero.
When a thread has finished using the resource, it calls ReleaseSemaphore to increment the semaphore's count. This can release one or more threads that are waiting for the semaphore.
It is recommended that you use the CreateSemaphoreW function for new development to ensure proper Unicode support.
If the lpName parameter is not NULL, the semaphore object is visible system-wide and can be accessed by any process that knows its name. This can be a security risk if the semaphore is used to protect sensitive resources. Consider using a unique name that is not easily guessable, or use ACLs to restrict access to the semaphore.
| Minimum supported client | Windows 2000 Professional |
| Minimum supported server | Windows 2000 Server |
| Header | winbase.h |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |