CreateMutexA-Funktion (synchapi.h)

Artikel
03/02/2024

Erstellt oder öffnet ein benanntes oder unbenannte Mutex-Objekt.

Verwenden Sie die CreateMutexEx-Funktion , um eine Zugriffsmaske für das Objekt anzugeben.

Syntax

HANDLE CreateMutexA(
  [in, optional] LPSECURITY_ATTRIBUTES lpMutexAttributes,
  [in]           BOOL                  bInitialOwner,
  [in, optional] LPCSTR                lpName
);

Parameter

[in, optional] lpMutexAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur . Wenn dieser Parameter NULL ist, kann das Handle nicht von untergeordneten Prozessen geerbt werden.

Der lpSecurityDescriptor-Member der -Struktur gibt einen Sicherheitsdeskriptor für den neuen Mutex an. Wenn lpMutexAttributesNULL ist, erhält der Mutex einen Standardsicherheitsdeskriptor. Die ACLs im Standardsicherheitsdeskriptor für einen Mutex stammen aus dem primären Token oder dem Identitätswechseltoken des Erstellers. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Synchronisierungsobjekte.

[in] bInitialOwner

Wenn dieser Wert TRUE ist und der Aufrufer den Mutex erstellt hat, erhält der aufrufende Thread den ursprünglichen Besitz des Mutex-Objekts. Andernfalls erhält der aufrufende Thread nicht den Besitz des Mutex. Informationen dazu, ob der Aufrufer den Mutex erstellt hat, finden Sie im Abschnitt Rückgabewerte.

[in, optional] lpName

Der Name des Mutex-Objekts. Der Name ist auf MAX_PATH Zeichen beschränkt. Beim Namenvergleich wird die Groß-/Kleinschreibung beachtet.

Wenn lpName mit dem Namen eines vorhandenen benannten Mutex-Objekts übereinstimmt, fordert diese Funktion das MUTEX_ALL_ACCESS Zugriffsrecht an. In diesem Fall wird der bInitialOwner-Parameter ignoriert, da er bereits vom Erstellungsprozess festgelegt wurde. Wenn der lpMutexAttributes-Parameter nicht NULL ist, bestimmt er, ob das Handle geerbt werden kann, sein Sicherheitsdeskriptorelement wird jedoch ignoriert.

Wenn lpNameNULL ist, wird das Mutex-Objekt ohne Namen erstellt.

Wenn lpName mit dem Namen eines vorhandenen Ereignisses, Semaphors, wartebaren Timers, Auftrags oder Dateizuordnungsobjekts übereinstimmt, schlägt die Funktion fehl, und die GetLastError-Funktion gibt ERROR_INVALID_HANDLE zurück. Dies liegt daran, dass diese Objekte denselben Namespace verwenden.

Der Name kann ein Präfix "Global" oder "Local" aufweisen, um das Objekt explizit im globalen Oder Sitzungsnamespace zu erstellen. Der Rest des Namens kann ein beliebiges Zeichen mit Ausnahme des umgekehrten Schrägstrichs (\) enthalten. Weitere Informationen finden Sie unter Kernelobjektnamespaces. Der schnelle Benutzerwechsel wird mithilfe von Terminaldienstesitzungen implementiert. Kernelobjektnamen müssen den Richtlinien für Terminaldienste entsprechen, damit Anwendungen mehrere Benutzer unterstützen können.

Das Objekt kann in einem privaten Namespace erstellt werden. Weitere Informationen finden Sie unter Objektnamespaces.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das neu erstellte Mutex-Objekt.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Wenn der Mutex ein benannter Mutex ist und das Objekt vor diesem Funktionsaufruf vorhanden war, ist der Rückgabewert ein Handle für das vorhandene Objekt, und die GetLastError-Funktion gibt ERROR_ALREADY_EXISTS zurück.

Hinweise

Das von CreateMutex zurückgegebene Handle verfügt über das zugriffsrecht MUTEX_ALL_ACCESS ; Sie kann in jeder Funktion verwendet werden, die ein Handle für ein Mutex-Objekt erfordert, vorausgesetzt, dem Aufrufer wurde Zugriff gewährt. Wenn ein Mutex aus einem Dienst oder thread erstellt wird, der die Identität eines anderen Benutzers angibt, können Sie entweder beim Erstellen einen Sicherheitsdeskriptor auf den Mutex anwenden oder den Standardsicherheitsdeskriptor für den Erstellungsprozess ändern, indem Sie dessen Standard-DACL ändern. Weitere Informationen finden Sie unter Sicherheit und Zugriffsrechte für Synchronisierungsobjekte.

Wenn Sie einen benannten Mutex verwenden, um Ihre Anwendung auf eine einzelne instance zu beschränken, kann ein böswilliger Benutzer diesen Mutex erstellen, bevor Sie dies tun, und verhindern, dass Ihre Anwendung gestartet wird. Um dies zu verhindern, erstellen Sie einen zufällig benannten Mutex, und speichern Sie den Namen, sodass er nur von einem autorisierten Benutzer abgerufen werden kann. Alternativ können Sie zu diesem Zweck eine Datei verwenden. Um Ihre Anwendung auf eine instance pro Benutzer zu beschränken, erstellen Sie eine gesperrte Datei im Profilverzeichnis des Benutzers.

Jeder Thread des aufrufenden Prozesses kann das Mutex-Objekthandle in einem Aufruf einer der Wartefunktionen angeben. Die Wartefunktionen für einzelne Objekte geben zurück, wenn der Zustand des angegebenen Objekts signalisiert wird. Die Wartefunktionen für mehrere Objekte können angewiesen werden, entweder zurückzugeben, wenn eine oder alle angegebenen Objekte signalisiert werden. Wenn eine Wartefunktion zurückgegeben wird, wird der wartende Thread freigegeben, um seine Ausführung fortzusetzen.

Der Zustand eines Mutex-Objekts wird signalisiert, wenn es sich nicht im Besitz eines Threads befindet. Der erstellende Thread kann das bInitialOwner-Flag verwenden, um den sofortigen Besitz des Mutex anzufordern. Andernfalls muss ein Thread eine der Wartefunktionen verwenden, um den Besitz anzufordern. Wenn der Status des Mutex signalisiert wird, wird einem wartenden Thread der Besitz gewährt, der Zustand des Mutex ändert sich in nicht signalisiert, und die Wartefunktion wird zurückgegeben. Nur ein Thread kann zu einem bestimmten Zeitpunkt einen Mutex besitzen. Der besitzende Thread verwendet die ReleaseMutex-Funktion , um seinen Besitz freizugeben.

Der Thread, der einen Mutex besitzt, kann den gleichen Mutex in wiederholten Wartefunktionsaufrufen angeben, ohne dessen Ausführung zu blockieren. In der Regel würden Sie nicht wiederholt auf denselben Mutex warten, aber dieser Mechanismus verhindert, dass ein Thread selbst deadlockt, während er auf einen Mutex wartet, den er bereits besitzt. Um jedoch seinen Besitz freizugeben, muss der Thread ReleaseMutex einmal für jedes Mal aufrufen, wenn der Mutex eine Wartezeit erfüllt hat.

Zwei oder mehr Prozesse können CreateMutex aufrufen, um denselben benannten Mutex zu erstellen. Der erste Prozess erstellt tatsächlich den Mutex, und nachfolgende Prozesse mit ausreichenden Zugriffsrechten öffnen einfach ein Handle für den vorhandenen Mutex. Dies ermöglicht es mehreren Prozessen, Handles desselben Mutex abzurufen, während der Benutzer von der Verantwortung entkommt, sicherzustellen, dass der Erstellungsprozess zuerst gestartet wird. Wenn Sie diese Technik verwenden, sollten Sie das Flag bInitialOwner auf FALSE festlegen. Andernfalls kann es schwierig sein, sicher zu sein, welcher Prozess den ursprünglichen Besitz besitzt.

Mehrere Prozesse können über Handles desselben Mutex-Objekts verfügen, sodass das Objekt für die Prozessübergreifende Synchronisierung verwendet werden kann. Die folgenden Mechanismen für die Objektfreigabe sind verfügbar:

Ein von der CreateProcess-Funktion erstellter untergeordneter Prozess kann ein Handle an ein Mutex-Objekt erben, wenn der lpMutexAttributes-Parameter von CreateMutex die Vererbung aktiviert hat. Dieser Mechanismus funktioniert sowohl für benannte als auch für unbenannte Mutexe.
Ein Prozess kann das Handle für ein Mutex-Objekt in einem Aufruf der DuplicateHandle-Funktion angeben, um ein doppeltes Handle zu erstellen, das von einem anderen Prozess verwendet werden kann. Dieser Mechanismus funktioniert sowohl für benannte als auch für unbenannte Mutexe.
Ein Prozess kann einen benannten Mutex in einem Aufruf von [OpenMutex](./nf-synchapi-openmutexw.md) oder CreateMutexex angeben, um ein Handle für das Mutex-Objekt abzurufen.

Verwenden Sie die CloseHandle-Funktion , um das Handle zu schließen. Das System schließt das Handle automatisch, wenn der Prozess beendet wird. Das Mutex-Objekt wird zerstört, wenn das letzte Handle geschlossen wurde.

Beispiele

Ein Beispiel für CreateMutex finden Sie unter Verwenden von Mutex-Objekten.

Hinweis

Der synchapi.h-Header definiert CreateMutex als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	synchapi.h (enthalten Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll