INtime SDK Help
CreateSemaphore, RtCreateSemaphore (iwin32)
INtime SDK v7.1 > About INtime > Alternate APIs > iwin32 API > iwin32 API > CreateSemaphore, RtCreateSemaphore (iwin32)

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

Versions Defined in Include Link to
INtime 3.0 intime/rt/include/iwin32.h
intime/rt/include/winbase.h
iwin32.h
windows.h
iwin32.lib

Notes

See Also

CloseHandle, ReleaseSemaphore, iwin32 API, iwin32 Overview