CreateMutexA-Funktion (synchapi.h)
Erstellt oder öffnet ein benanntes oder unbenannte Mutex -Objekt.
Verwenden Sie die CreateMutexEx--Funktion, um ein Zugriffsformat 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 Element 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 oder Identitätswechseltoken des Erstellers. Weitere Informationen finden Sie unter Sync Object Security and Access Rights.
[in] bInitialOwner
Wenn dieser Wert TRUE und der Aufrufer den Mutex erstellt hat, erhält der aufrufende Thread den anfänglichen Besitz des Mutex-Objekts. Andernfalls erhält der aufrufende Thread keinen 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. Bei dem Namensvergleich wird die Groß-/Kleinschreibung beachtet.
Wenn lpName- dem Namen eines vorhandenen benannten Mutex-Objekts entspricht, 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, aber sein Sicherheitsdeskriptorelement wird ignoriert.
Wenn lpName-NULL-ist, wird das Mutex-Objekt ohne Namen erstellt.
Wenn lpName- dem Namen eines vorhandenen Ereignisses, Semaphoren, Wartezeitgeber-, Auftrags- oder Dateizuordnungsobjekts entspricht, schlägt die Funktion fehl, und die GetLastError--Funktion gibt ERROR_INVALID_HANDLEzurück. Dies geschieht, da diese Objekte denselben Namespace gemeinsam nutzen.
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 Kernel Object Namespaces. Schnelle Benutzerumschaltung 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 Object Namespaces.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das neu erstellte Mutex-Objekt.
Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL-. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Wenn es sich bei dem Mutex um einen benannten Mutex handelt und das Objekt vor diesem Funktionsaufruf vorhanden ist, ist der Rückgabewert ein Handle für das vorhandene Objekt, und die GetLastError-Funktion gibt ERROR_ALREADY_EXISTSzurück.
Bemerkungen
Der von CreateMutex zurückgegebene Handle hat das MUTEX_ALL_ACCESS Zugriffsrecht; sie kann in jeder Funktion verwendet werden, für die ein Handle für ein Mutex-Objekt erforderlich ist, vorausgesetzt, der Aufrufer wurde Zugriff gewährt. Wenn ein Mutex aus einem Dienst oder einem Thread erstellt wird, der die Identität eines anderen Benutzers angibt, können Sie beim Erstellen entweder einen Sicherheitsdeskriptor auf den Mutex anwenden oder den Standardsicherheitsdeskriptor für den Erstellungsprozess ändern, indem Sie die standardmäßige DACL ändern. Weitere Informationen finden Sie unter Sync Object Security and Access Rights.
Wenn Sie einen benannten Mutex verwenden, um Ihre Anwendung auf eine einzelne Instanz zu beschränken, kann ein böswilliger Benutzer diesen Mutex erstellen, bevor Sie die Anwendung starten und verhindern. Um diese Situation zu verhindern, erstellen Sie einen zufällig benannten Mutex, und speichern Sie den Namen so, dass er nur von einem autorisierten Benutzer abgerufen werden kann. Alternativ können Sie eine Datei für diesen Zweck verwenden. Um Ihre Anwendung auf eine Instanz 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 Wait-Funktionenangeben. Die Einzelobjekt-Wait-Funktionen werden zurückgegeben, wenn der Status des angegebenen Objekts signalisiert wird. Die Wait-Funktionen mit mehreren Objekten können angewiesen werden, entweder zurückzugeben, wenn eines oder alle angegebenen Objekte signalisiert werden. Wenn eine Wartefunktion zurückgegeben wird, wird der Wartethread losgelassen, um die Ausführung fortzusetzen.
Der Status eines Mutex-Objekts wird signalisiert, wenn es keinem Thread gehört. Der Erstellungsthread kann die 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, erhält ein Wartethread den Besitz, der Status des Mutex ändert sich in nicht signalisiert, und die Wartefunktion wird zurückgegeben. Nur ein Thread kann jederzeit einen Mutex besitzen. Der besitzereigene Thread verwendet die ReleaseMutex--Funktion, um den Besitz freizugeben.
Der Thread, der ein Mutex besitzt, kann den gleichen Mutex in wiederholten Wartefunktionsaufrufen angeben, ohne die Ausführung zu blockieren. In der Regel würden Sie nicht wiederholt auf denselben Mutex warten, aber dieser Mechanismus verhindert, dass ein Thread sich selbst blockiert, während er auf einen Mutex wartet, den er bereits besitzt. Um den Besitz freizugeben, muss der Thread jedoch ReleaseMutex- einmal 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 einen Handle für den vorhandenen Mutex. Auf diese Weise können mehrere Prozesse den gleichen Mutex abrufen und gleichzeitig den Benutzer von der Verantwortung entlasten, sicherzustellen, dass der Erstellungsprozess zuerst gestartet wird. Bei Verwendung dieser Technik sollten Sie die bInitialOwner- Flag auf FALSE-festlegen; andernfalls kann es schwierig sein, sicher zu sein, welcher Prozess über den ursprünglichen Besitz verfügt.
Mehrere Prozesse können Überhandles desselben Mutex-Objekts verfügen, wodurch die Verwendung des Objekts für die Interprocess-Synchronisierung ermöglicht wird. Die folgenden Objektfreigabemechanismen sind verfügbar:
- Ein untergeordneter Prozess, der von der CreateProcess-Funktion erstellt wird, kann ein Handle an ein Mutex-Objekt erben, wenn der lpMutexAttributes Parameter von CreateMutex aktivierte Vererbung. Dieser Mechanismus funktioniert sowohl für benannte als auch für unbenannte Mutexes.
- Ein Prozess kann das Handle für ein Mutex-Objekt in einem Aufruf der DuplicateHandle--Funktion angeben, um ein dupliziertes Handle zu erstellen, das von einem anderen Prozess verwendet werden kann. Dieser Mechanismus funktioniert sowohl für benannte als auch für unbenannte Mutexes.
- Ein Prozess kann einen benannten Mutex in einem Aufruf von [OpenMutex](./nf-synchapi-openmutexw.md) oder CreateMutex angeben, um ein Handle für das Mutex-Objekt abzurufen.
Beispiele
Ein Beispiel für CreateMutex-finden Sie unter Verwenden von Mutex-Objekten.
Anmerkung
Der header synchapi.h 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 |
|---|---|
| mindestens unterstützte Client- | Windows XP [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | synchapi.h (enthalten Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |