CreateMutexA, fonction (synchapi.h)

Article
08/26/2023

Crée ou ouvre un objet mutex nommé ou sans nom.

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

Syntaxe

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

Paramètres

[in, optional] lpMutexAttributes

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 mutex. Si lpMutexAttributes a la valeur NULL, le mutex 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 pour un mutex proviennent du jeton principal ou d’emprunt d’identité du créateur. Pour plus d’informations, consultez Synchronisation des droits d’accès et de sécurité des objets.

[in] bInitialOwner

Si cette valeur est TRUE et que l’appelant a créé le mutex, le thread appelant obtient la propriété initiale de l’objet mutex. Sinon, le thread appelant n’obtient pas la propriété du mutex. Pour déterminer si l’appelant a créé le mutex, consultez la section Valeurs de retour.

[in, optional] lpName

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

Si lpName correspond au nom d’un objet mutex nommé existant, cette fonction demande le droit d’accès MUTEX_ALL_ACCESS . Dans ce cas, le paramètre bInitialOwner est ignoré, car il a déjà été défini par le processus de création. Si le paramètre lpMutexAttributes n’est pas NULL, il détermine si le handle peut être hérité, mais son membre security-descripteur est ignoré.

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

Si lpName correspond au nom d’un événement, d’un sémaphore, 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 de la barre oblique inverse (\). Pour plus d’informations, consultez Espaces de noms d’objets du noyau. La commutation rapide des utilisateurs est implémentée à l’aide de sessions Terminal Services. Les noms d’objets de noyau doivent suivre les instructions décrites pour Terminal Services 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 pour l’objet mutex nouvellement créé.

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

Si le mutex est un mutex nommé et que l’objet existait avant cet appel de fonction, la valeur de retour est un handle pour l’objet existant et la fonction GetLastError retourne ERROR_ALREADY_EXISTS.

Remarques

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

Si vous utilisez un mutex nommé pour limiter votre application à un seul instance, un utilisateur malveillant peut créer ce mutex avant de le faire et empêcher le démarrage de votre application. Pour éviter cette situation, créez un mutex nommé de façon aléatoire et stockez le nom afin qu’il ne puisse être obtenu que par un utilisateur autorisé. Vous pouvez également utiliser un fichier à cette fin. Pour limiter votre application à un instance par utilisateur, créez un fichier verrouillé dans le répertoire de profil de l’utilisateur.

N’importe quel thread du processus appelant peut spécifier le handle d’objet mutex 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 lorsque tous les objets spécifiés sont signalés. Lorsqu’une fonction d’attente est retournée, le thread en attente est libéré pour poursuivre son exécution.

L’état d’un objet mutex est signalé lorsqu’il n’appartient à aucun thread. Le thread de création peut utiliser l’indicateur bInitialOwner pour demander la propriété immédiate du mutex. Sinon, un thread doit utiliser l’une des fonctions d’attente pour demander la propriété. Lorsque l’état du mutex est signalé, un thread en attente reçoit la propriété, l’état du mutex passe à non signé et la fonction wait retourne. Un seul thread peut posséder un mutex à un moment donné. Le thread propriétaire utilise la fonction ReleaseMutex pour libérer sa propriété.

Le thread qui possède un mutex peut spécifier le même mutex dans les appels de fonction d’attente répétés sans bloquer son exécution. En règle générale, vous n’attendez pas à plusieurs reprises le même mutex, mais ce mécanisme empêche un thread de se bloquer tout en attendant un mutex qu’il possède déjà. Toutefois, pour libérer sa propriété, le thread doit appeler ReleaseMutex une fois pour chaque fois que le mutex a satisfait à une attente.

Au moins deux processus peuvent appeler CreateMutex pour créer le même mutex nommé. Le premier processus crée en fait le mutex, et les processus suivants avec des droits d’accès suffisants ouvrent simplement un handle au mutex existant. Cela permet à plusieurs processus d’obtenir des handles du même mutex, tout en soulageant l’utilisateur de la responsabilité de s’assurer que le processus de création est démarré en premier. Lorsque vous utilisez cette technique, vous devez définir l’indicateur bInitialOwner sur FALSE ; dans le cas contraire, il peut être difficile d’être certain que le processus a la propriété initiale.

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

Un processus enfant créé par la fonction CreateProcess peut hériter d’un handle à un objet mutex si le paramètre lpMutexAttributes de l’héritage CreateMutex activé. Ce mécanisme fonctionne pour les mutex nommés et non nommés.
Un processus peut spécifier le handle d’un objet mutex dans un appel à la fonction DuplicateHandle pour créer un handle en double qui peut être utilisé par un autre processus. Ce mécanisme fonctionne pour les mutex nommés et non nommés.
Un processus peut spécifier un mutex nommé dans un appel à [OpenMutex](./nf-synchapi-openmutexw.md) ou à CreateMutex pour récupérer un handle pour l’objet mutex.

Utilisez la fonction CloseHandle pour fermer le handle. Le système ferme automatiquement le handle à l’arrêt du processus. L’objet mutex est détruit lorsque son dernier handle a été fermé.

Exemples

Pour obtenir un exemple de CreateMutex, consultez Utilisation d’objets Mutex.

Notes

L’en-tête synchapi.h définit CreateMutex en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
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	synchapi.h (inclure Windows.h sur Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll