Creates or opens a mutex.

HANDLE RtCreateMutex(

    LPSECURITY_ATTRIBUTES lpMutexAttributes,

    BOOLEAN bInitialOwner,

    LPCTSTR lpName

);

Parameters

lpMutexAttributes

Ignored. Must be NULL.

bInitialOwner

Specifies the initial owner of the mutex object:

TRUE and the caller created the mutex

Calling thread obtains ownership of the mutex object. To determine if the caller created the mutex, see the Return Values section.

FALSE

Calling thread does not obtain ownership of the mutex.

lpName

Pointer to a null-terminated string that specifies the mutex object's name. 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 object is created without a name.

Matches an existing named mutex object

Ignores the bInitialOwner parameter because it was already set by the creation process.

Matches the name of an existing event, semaphore, or shared memory object

The function fails and the Windows' GetLastError function returns ERROR_INVALID_HANDLE. This occurs because these objects share the same name space.

Return Values

Handle to mutex object

Success.

Handle to existing object and ERROR_ALREADY_EXISTS

The mutex object existed before the function call.

NULL

Failure. For extended error information, see the Windows' GetLastError function.

Requirements

Notes

• This function operates in the Windows portion of your application.
• The iwin32 API also includes an RtCreateMutex function that operates in the real-time portion of your application.

See Also

iwin32x API, iwin32 Overview