RtkCreateSemaphore

RtkCreateSemaphore creates a named semaphore object.

Syntax

HANDLE RtkCreateSemaphore(
    RTSSINST RtssInst,
    PULONG pErrorCode,
    LPSECURITY_ATTRIBUTES pSecurity,
    LONG lInitialCount,
    LONG lMaximumCount,
    PUNICODE_STRING lpName
);

Parameters

RtssInst

An RTSSINST value returned from a call to RtkRtssAttach.

pErrorCode

A pointer to a location where additional error information may be returned. This location need not be defined; the user may pass a NULL value. If defined, this location is set to NULL if no error occurred.

pSecurity

Ignored. A pointer to a SECURITY_ATTRIBUTES structure.

lpSemaphoreAttributes (ignored)

A pointer to security attributes.

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 RtkReleaseSemaphore.

lMaximumCount

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

lpName

A pointer to a PUNICODE_STRING specifying the name of the mutex object. The name is limited to RTX_MAX_PATH 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.

Return Values

A handle to the semaphore object if the function succeeds

NOTE: If the named semaphore object existed before the function call, pErrorCode is set to ERROR_ALREADY_EXISTS.

ERROR_INVALID_HANDLE if the function fails (for example, if lpName matches the name of an existing semaphore)

NOTE: This occurs because mutex and semaphore objects share the same name space.

Remarks

The handle returned by RtkCreateSemaphore 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 one or when all of the specified objects are signaled. When a wait function returns, the waiting thread is released to continue its execution.

The state of a semaphore object is signaled when its count is greater than zero, and non-signaled when its count is equal to zero. lInitialCount specifies the initial count. Each time a waiting thread is released because of the semaphore's signaled state, the count of the semaphore is decreased by one. Use RtkReleaseSemaphore to increment a semaphore's count by a specified amount. The count can never be less than zero or greater than the value specified in lMaximumCount.

Multiple processes can have handles of the same semaphore object, enabling use of the object for interprocess synchronization. The available object-sharing mechanism is: A process can specify the name of a semaphore object in a call to RtkOpenSemaphore or RtkCreateSemaphore.

Use RtkCloseHandle 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.

Requirements

Header	Rtkapi.h
Library	rtx_rtk.lib