CreateMutex

The CreateMutex function creates a named or unnamed mutex object and returns a handle to the object.

Parameters

lpsa

Points to a SECURITY_ATTRIBUTES data structure that specifies the security attributes for the mutex.

The SECURITY_ATTRIBUTES structure has the following format:

typedef struct _SECURITY_ATTRIBUTES { /* sa */

DWORD nLength;

LPVOID lpSecurityDescriptor;

BOOL bInheritHandle;

} SECURITY_ATTRIBUTES;

If lpsa is NULL, the mutex is created without a security descriptor, and the resulting handle cannot be inherited.

fInitialOwner

Specifies initial ownership of the mutex. If fInitailOwner is TRUE, the creator of the mutex desires immediate ownership.

lpszMutexName

Points to a null-terminated string specifying the name of the mutex. The name may contain any character except the pathname separator character '\'.

If lpszMutexName matches the name of an existing named object, this function requests ALL access to the existing mutex (this is similar to calling the OpenMutex function).

If lpszMutexName is NULL, the mutex is created without a name.

Return Value

If the function is successful, the return value is a handle to the mutex. If the mutex existed before the function call, the GetLastError function returns ERROR_ALREADY_EXISTS. If the mutex did not exist, GetLastError returns zero.

If the function fails, the return value is NULL. Use the GetLastError function to obtain extended error information.

Comments

To implement a mutex creation function that fails if the mutex already exists, an application can use the following code:

hMutex = CreateMutex(...);

if (hMutex != NULL && GetLastError() == ERROR_ALREADY_EXISTS) {

CloseHandle(hMutex);

hMutex = NULL;

}

return hMutex;

The CreateMutex function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).

The returned handle has full access to the new mutex object. It may be used with any function that requires a handle to a mutex object.

In addition to the standard object sharing mechanisms available in Win32 — inheritance and the DuplicateHandle function — named mutexes may be opened by any thread with appropriate access using OpenMutex. This allows the mutex object to be shared by any application that knows the name of the mutex.

In addition to the STANDARD_RIGHTS_REQUIRED access flags, the following object type specific access flags are valid for mutex objects:

These object specific access flags are used when duplicating the mutex handle via DuplicateHandle.

See Also

CloseHandle, OpenMutex, WaitForSingleObject, WaitForMultipleObjects