RtCreateSemaphore

RtCreateSemaphore creates a named or unnamed semaphore object.

Syntax

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

Parameters

lpSemaphoreAttributes

Ignored.

lInitialCount

An initial count for the semaphore object. This value must be greater than or equal to zero and less than or equal to lMaximumCount. The state of a semaphore is signaled when its count is greater than zero and non-signaled when it is zero. The count is decreased by one whenever a wait function releases a thread that was waiting for the semaphore. The count is increased by a specified amount by calling RtReleaseSemaphore.

lMaximumCount

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

lpName

A pointer to a null-terminated string specifying the name of the semaphore object. The name is limited to 260 characters, and can contain any character except the backslash path-separator character (\). Name comparison is case-sensitive.

If lpName matches the name of an existing named semaphore object, this function requests access to the existing object. In this case, lInitialCount and lMaximumCount are ignored because they have already been set by the creating process.

If lpName matches the name of an existing event, mutex, or shared memory object, the function fails and GetLastError returns ERROR_INVALID_HANDLE. This occurs because event, mutex, semaphore, and shared memory objects share the same namespace.

If lpName is NULL, the semaphore object is created without a name.

Return Value

A handle to the semaphore object if the function succeeds, NULL if the function fails

To get extended error information, call GetLastError.

If the named semaphore object existed before the function call, GetLastError returns ERROR_ALREADY_EXISTS. Otherwise, GetLastError returns zero.

Remarks

The handle returned by RtCreateSemaphore has all accesses to the new semaphore object and can be used in any function that requires a handle to a semaphore object.

Any thread of the calling process can specify the semaphore-object handle in a call to one of the wait functions. The single-object wait functions return when the state of the specified object is signaled. The multiple-object wait functions can be instructed to return either when any object is signaled. When a wait function returns, the waiting thread is released to continue its execution.

Multiple processes can have handles to the same named semaphore object, enabling use of the object for interprocess synchronization. The available object-sharing mechanism is a process that can specify the name of a semaphore object in a call to RtOpenSemaphore or RtCreateSemaphore.

Use RtCloseHandle to close the handle. The system closes the handle automatically when the process terminates. The semaphore object is destroyed when its last handle has been closed.

See Also:

RtCloseHandle

RtOpenSemaphore

RtReleaseSemaphore