Creates a named or unnamed mutex object.

HANDLE CreateMutex(
    LPSECURITY_ATTRIBUTES lpMutexAttributes,
    BOOLEAN bInitialOwner,
    LPCTSTR lpName
);

HANDLE RtCreateMutex(
    LPSECURITY_ATTRIBUTES lpMutexAttributes,
    BOOLEAN bInitialOwner,
    LPCTSTR lpName
);

Parameters

lpMutexAttributes

Ignored. Must be set to 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 GetLastError returns ERROR_INVALID_HANDLE. This occurs because these objects share the same name space.

Remarks

The mutex object's state is signaled when no thread owns it. The creating thread can use the bInitialOwner flag to request immediate mutex ownership. Otherwise, a thread must use a wait function to request ownership. When the mutex's state is signaled, one waiting thread is granted ownership, the mutex's state changes to nonsignaled, and the wait function returns. Only one thread can own a mutex at any given time. The owning thread uses ReleaseMutex to release its ownership.

The thread that owns a mutex can specify the same mutex in repeated wait function calls without blocking its execution. Typically, the thread would not wait repeatedly for the same mutex, but this mechanism prevents a thread from deadlocking itself while waiting for a mutex that it already owns. However, to release its ownership, the thread must call ReleaseMutex once for each time that the mutex satisfied a wait.

Two or more processes can call CreateMutex to create the same named mutex. The first process actually creates the mutex, and subsequent processes open a handle to the existing mutex. This enables multiple processes to get handles of the same mutex, while relieving you of the responsibility of ensuring that the creating process is started first. When using this technique, set the bInitialOwner flag to FALSE; otherwise, it can be difficult to determine which process has initial ownership.

Multiple processes can have handles of the same mutex object, enabling use of the object for interprocess synchronization. To provide object sharing, a process can specify the name of a mutex object in a call to CreateMutex.

To close the handle, use CloseHandle. The system automatically closes the handle when the process terminates. When its last handle closes, the mutex object is destroyed.

RtCreateMutex can also be used from a Windows application to create an iwin32 mutex.

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

Requirements

Notes

• In the iwin32 API, CreateMutex and RtCreateMutex are synonyms.
• This function operates in the real-time portion of your application.
• The iwin32x API also includes an RtCreateMutex function that operates in the Windows portion of your application.

See Also

CloseHandle, ReleaseMutex, iwin32 API, iwin32 Overview