CreateSemaphoreA, fonction (winbase.h)

Article
06/10/2023

Crée ou ouvre un objet sémaphore nommé ou non nommé.

Pour spécifier un masque d’accès pour l’objet, utilisez la fonction CreateSemaphoreEx .

Syntaxe

HANDLE CreateSemaphoreA(
  [in, optional] LPSECURITY_ATTRIBUTES lpSemaphoreAttributes,
  [in]           LONG                  lInitialCount,
  [in]           LONG                  lMaximumCount,
  [in, optional] LPCSTR                lpName
);

Paramètres

[in, optional] lpSemaphoreAttributes

Pointeur vers une structure SECURITY_ATTRIBUTES . Si ce paramètre a la valeur NULL, le handle ne peut pas être hérité par les processus enfants.

Le membre lpSecurityDescriptor de la structure spécifie un descripteur de sécurité pour le nouveau sémaphore. Si ce paramètre a la valeur NULL, le sémaphore obtient un descripteur de sécurité par défaut. Les listes de contrôle d’accès dans le descripteur de sécurité par défaut d’un sémaphore proviennent du jeton principal ou d’emprunt d’identité du créateur.

[in] lInitialCount

Nombre initial de l’objet sémaphore. Cette valeur doit être supérieure ou égale à zéro et inférieure ou égale à lMaximumCount. L’état d’un sémaphore est signalé lorsque son nombre est supérieur à zéro et non signé lorsqu’il est égal à zéro. Le nombre est réduit d’un chaque fois qu’une fonction d’attente libère un thread qui attendait le sémaphore. Le nombre est augmenté d’un montant spécifié en appelant la fonction ReleaseSemaphore .

[in] lMaximumCount

Nombre maximal pour l’objet sémaphore. Cette valeur doit être supérieure à zéro.

[in, optional] lpName

Nom de l’objet sémaphore. Le nom est limité à MAX_PATH caractères. La comparaison de noms respecte la casse.

Si lpName correspond au nom d’un objet sémaphore nommé existant, cette fonction demande le droit d’accès SEMAPHORE_ALL_ACCESS . Dans ce cas, les paramètres lInitialCount et lMaximumCount sont ignorés, car ils ont déjà été définis par le processus de création. Si le paramètre lpSemaphoreAttributes n’a pas la valeur NULL, il détermine si le handle peut être hérité, mais si son membre de descripteur de sécurité est ignoré.

Si lpName a la valeur NULL, l’objet sémaphore est créé sans nom.

Si lpName correspond au nom d’un événement, d’un mutex, d’un minuteur d’attente, d’un travail ou d’un objet de mappage de fichiers existant, la fonction échoue et la fonction GetLastError retourne ERROR_INVALID_HANDLE. Cela se produit parce que ces objets partagent le même espace de noms.

Le nom peut avoir un préfixe « Global » ou « Local » pour créer explicitement l’objet dans l’espace de noms global ou de session. Le reste du nom peut contenir n’importe quel caractère à l’exception du caractère barre oblique inverse (\). Pour plus d’informations, consultez Espaces de noms d’objets de noyau. Le changement rapide d’utilisateur est implémenté à l’aide de sessions Terminal Services. Les noms d’objets de noyau doivent suivre les instructions décrites pour les services Terminal Server afin que les applications puissent prendre en charge plusieurs utilisateurs.

L’objet peut être créé dans un espace de noms privé. Pour plus d’informations, consultez Espaces de noms d’objets.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle de l’objet sémaphore. Si l’objet sémaphore nommé existait avant l’appel de fonction, la fonction retourne un handle à l’objet existant et GetLastError retourne ERROR_ALREADY_EXISTS.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Notes

Le handle retourné par CreateSemaphore a le droit d’accès SEMAPHORE_ALL_ACCESS ; il peut être utilisé dans n’importe quelle fonction qui nécessite un handle pour un objet sémaphore, à condition que l’appelant ait obtenu l’accès. Si un sémaphore est créé à partir d’un service ou d’un thread qui emprunte l’identité d’un autre utilisateur, vous pouvez soit appliquer un descripteur de sécurité au sémaphore lorsque vous le créez, soit modifier le descripteur de sécurité par défaut pour le processus de création en modifiant son dacl par défaut. Pour plus d’informations, consultez Synchronisation Des droits d’accès et de sécurité des objets.

L’état d’un objet sémaphore est signalé lorsque son nombre est supérieur à zéro et non signé lorsque son nombre est égal à zéro. Le paramètre lInitialCount spécifie le nombre initial. Le nombre ne peut jamais être inférieur à zéro ou supérieur à la valeur spécifiée dans le paramètre lMaximumCount .

N’importe quel thread du processus appelant peut spécifier le handle sémaphore-objet dans un appel à l’une des fonctions d’attente. Les fonctions d’attente à objet unique retournent lorsque l’état de l’objet spécifié est signalé. Les fonctions d’attente à plusieurs objets peuvent être indiquées pour retourner l’un ou l’autre des objets spécifiés. Lorsqu’une fonction d’attente retourne, le thread d’attente est libéré pour poursuivre son exécution. Chaque fois qu’un thread termine une attente pour un objet sémaphore, le nombre de l’objet sémaphore est décrémenté par un. Une fois le thread terminé, il appelle la fonction ReleaseSemaphore, qui incrémente le nombre de l’objet sémaphore.

Plusieurs processus peuvent avoir des handles du même objet sémaphore, ce qui permet d’utiliser l’objet pour la synchronisation interprocess. Les mécanismes de partage d’objets suivants sont disponibles :

Un processus enfant créé par la fonction CreateProcess peut hériter d’un handle vers un objet sémaphore si le paramètre lpSemaphoreAttributes de l’héritage CreateSemaphore est activé.
Un processus peut spécifier le handle sémaphore-object dans un appel à la fonction DuplicateHandle pour créer un handle en double qui peut être utilisé par un autre processus.
Un processus peut spécifier le nom d’un objet sémaphore dans un appel à la fonction [OpenSemaphore](/windows/win32/api/synchapi/nf-synchapi-opensemaphorew) ou CreateSemaphore.

Utilisez la fonction CloseHandle pour fermer le handle. Le système ferme automatiquement le handle à l’arrêt du processus. L’objet sémaphore est détruit lorsque sa dernière poignée a été fermée.

Exemples

Pour obtenir un exemple qui utilise CreateSemaphore, consultez Utilisation d’objets sémaphore.

Configuration requise


Client minimal pris en charge	Windows XP [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll