CreateSemaphoreW-Funktion (synchapi.h)

Artikel
08/26/2023

Erstellt oder öffnet ein benanntes oder unbenannte Semaphorobjekt.

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

Syntax

HANDLE CreateSemaphoreW(
  [in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
  [in]           LONG                  lInitialCount,
  [in]           LONG                  lMaximumCount,
  [in, optional] LPCWSTR               lpName
);

Parameter

[in, optional] lpSemaphoreAttributes

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 das neue Semaphor an. Wenn dieser Parameter NULL ist, erhält der Semaphor einen Standardsicherheitsdeskriptor. Die ACLs im Standardsicherheitsdeskriptor für ein Semaphor stammen aus dem primären Token oder dem Identitätswechseltoken des Erstellers.

[in] lInitialCount

Die anfängliche Anzahl für das Semaphorobjekt. Dieser Wert muss größer oder gleich Null und kleiner oder gleich lMaximumCount sein. Der Zustand eines Semaphors wird signalisiert, wenn seine Anzahl größer als 0 ist, und nicht signalisiert, wenn er null ist. Die Anzahl wird um eins verringert, wenn eine Wartefunktion einen Thread freigibt, der auf den Semaphor wartete. Die Anzahl wird durch Aufrufen der ReleaseSemaphore-Funktion um einen angegebenen Betrag erhöht.

[in] lMaximumCount

Die maximale Anzahl für das Semaphorobjekt. Dieser Wert muss größer als 0 sein.

[in, optional] lpName

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

Wenn lpName mit dem Namen eines vorhandenen benannten Semaphorobjekts übereinstimmt, fordert diese Funktion das SEMAPHORE_ALL_ACCESS Zugriffsrecht an. In diesem Fall werden die Parameter lInitialCount und lMaximumCount ignoriert, da sie bereits vom Erstellungsprozess festgelegt wurden. Wenn der parameter lpSemaphoreAttributes nicht NULL ist, bestimmt er, ob das Handle geerbt werden kann, sein Sicherheitsdeskriptorelement wird jedoch ignoriert.

Wenn lpNameNULL ist, wird das Semaphorobjekt ohne Namen erstellt.

Wenn lpName mit dem Namen eines vorhandenen Ereignis-, Mutex-, Wartezeitgeber-, 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 Semaphorobjekt. Wenn das benannte Semaphorobjekt vor dem Funktionsaufruf vorhanden war, gibt die Funktion ein Handle an das vorhandene Objekt zurück, und GetLastError gibt ERROR_ALREADY_EXISTS zurück.

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

Hinweise

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

Der Zustand eines Semaphorobjekts wird signalisiert, wenn seine Anzahl größer als 0 ist, und nicht signalisiert, wenn seine Anzahl gleich 0 ist. Der lInitialCount-Parameter gibt die anfängliche Anzahl an. Die Anzahl darf nie kleiner als 0 (null) oder größer als der im lMaximumCount-Parameter angegebene Wert sein.

Jeder Thread des aufrufenden Prozesses kann das Handle semaphor-object 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. Jedes Mal, wenn ein Thread eine Wartezeit auf ein Semaphorobjekt abschließt, wird die Anzahl des Semaphorobjekts um eins verringert. Wenn der Thread fertig ist, ruft er die ReleaseSemaphore-Funktion auf, die die Anzahl des Semaphorobjekts erhöht.

Mehrere Prozesse können über Handles desselben Semaphorobjekts verfügen, wodurch die Verwendung des -Objekts für die Prozessübergreifende Synchronisierung ermöglicht wird. Die folgenden Mechanismen für die Objektfreigabe sind verfügbar:

Ein von der CreateProcess-Funktion erstellter untergeordneter Prozess kann ein Handle an ein Semaphorobjekt erben, wenn der lpSemaphoreAttributes-Parameter von CreateSemaphore die Vererbung aktiviert hat.
Ein Prozess kann das Handle semaphor-object in einem Aufruf der DuplicateHandle-Funktion angeben, um ein doppeltes Handle zu erstellen, das von einem anderen Prozess verwendet werden kann.
Ein Prozess kann den Namen eines Semaphorobjekts in einem Aufruf der OpenSemaphore- oder CreateSemaphore-Funktion angeben.

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

Beispiele

Ein Beispiel, das CreateSemaphor verwendet, finden Sie unter Verwenden von Semaphorobjekten.

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 (windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll