CreateMutexA, fonction (synchapi.h)

Article
11/20/2024

Crée ou ouvre un objet mutex nommé ou non nommé.

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 est NULL, le handle ne peut pas être hérité par les processus enfants.

Le lpSecurityDescriptor membre de la structure spécifie un descripteur de sécurité pour le nouveau mutex. Si lpMutexAttributes est 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 de descripteur de sécurité est ignoré.

Si lpName est 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, 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 de barre oblique inverse (\). Pour plus d’informations, consultez espaces de noms d’objets noyau. Le basculement rapide des utilisateurs est implémenté à l’aide de sessions Terminal Services. Les noms d’objets noyau doivent suivre les instructions décrites pour les services 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 de retour

Si la fonction réussit, la valeur de retour est un handle de l’objet mutex nouvellement créé.

Si la fonction échoue, la valeur de retour est NULL . Pour obtenir des informations d’erreur étendues, 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 dispose du droit d’accès MUTEX_ALL_ACCESS ; elle peut être utilisée dans n’importe quelle fonction qui nécessite un handle pour un objet mutex, à condition que l’appelant ait reçu 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 à une seule instance, un utilisateur malveillant peut créer ce mutex avant de commencer et empêcher votre application de démarrer. Pour éviter cette situation, créez un mutex nommé de façon aléatoire et stockez le nom afin qu’il puisse uniquement être obtenu par un utilisateur autorisé. Vous pouvez également utiliser un fichier à cet effet. Pour limiter votre application à une instance par utilisateur, créez un fichier verrouillé dans le répertoire de profil de l’utilisateur.

Tout thread du processus appelant peut spécifier le handle mutex-object 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 quand un ou lorsque tous les objets spécifiés sont signalés. Lorsqu’une fonction d’attente retourne, 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 d’attente retourne. Un seul thread peut posséder un mutex à tout moment. Le thread propriétaire utilise la fonction ReleaseMutex pour libérer sa propriété.

Le thread propriétaire d’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 qu’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 satisfait d’une attente.

Deux processus ou plus peuvent appeler CreateMutex pour créer le même mutex nommé. Le premier processus crée réellement 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 réduisant 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 FALSE; sinon, il peut être difficile d’être certain que le processus possède 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 entre processus. 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 à la fois pour les mutex nommés et sans nom.
Un processus peut spécifier le handle à 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 à la fois pour les mutex nommés et sans nom.
Un processus peut spécifier un mutex nommé dans un appel à [OpenMutex](./nf-synchapi-openmutexw.md) ou CreateMutex pour récupérer un handle sur l’objet mutex.

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

Exemples

Consultez Utilisation d’objets Mutex pour obtenir un exemple de CreateMutex.

Note

L’en-tête synchapi.h définit CreateMutex comme 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. Le mélange 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’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