CreateSemaphore

The CreateSemaphore function creates a named or unnamed semaphore object and returns a handle to the new semaphore.

Parameters

lpsa

Points to a SECURITY_ATTRIBUTES data structure that specifies the security attributes for the semaphore.

The SECURITY_ATTRIBUTES structure has the following format:

typedef struct _SECURITY_ATTRIBUTES { /* sa */

DWORD nLength;

LPVOID lpSecurityDescriptor;

BOOL bInheritHandle;

} SECURITY_ATTRIBUTES;

if lpsa is NULL, the semaphore is created without a security descriptor, and the resulting handle cannot be inherited.

cSemInitial

Specifies an initial count for the semaphore. This value must be greater than zero and less than or equal to cSemMax.

cSemMax

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

lpszSemName

Points to a null-terminated string specifying the name of the semaphore. The name may contain any character except the pathname separator character '\'.

If lpszSemName matches the name of an existing named object, this function requests ALL access to the existing semaphore (this is similar to calling the OpenSemaphore function).

If lpszSemName is NULL, the semaphore is created without a name.

Return Value

If the function is successful, the return value is a handle to the semaphore. If the semaphore existed before the function call, the GetLastError function returns ERROR_ALREADY_EXISTS. If the semaphore did not exist, GetLastError returns zero.

If the function fails, the return value is NULL. Use the GetLastError function to obtain extended error information.

Comments

To implement a semaphore creation function that fails if the semaphore already exists, an application can use the following code:

hSem = CreateSemaphore(...);

if (hSem != NULL && GetLastError() == ERROR_ALREADY_EXISTS) {

CloseHandle(hSem);

hSem = NULL;

}

return hSem;

The CreateSemaphore function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).

The handle that CreateSemaphore returns has full access to the new semaphore object. It may be used with any function that requires a handle to a semaphore object.

In addition to the standard object sharing mechanisms available in Win32 — inheritance and the DuplicateHandle function — named semaphores may be opened by any thread (with appropriate access) with the OpenSemaphore function. This allows the semaphore object to be shared by any application that knows the name of the semaphore.

In addition to the STANDARD_RIGHTS_REQUIRED access flags, the following object type specific access flags are valid for semaphore objects:

These object specific access flags are used when duplicating the semaphore handle via DuplicateHandle.

See Also

CloseHandle, OpenSemaphore, WaitForSingleObject, WaitForMultipleObjects