Funzione CreateMutexA (synchapi.h)

Crea o apre un oggetto mutex denominato o senza nome.

Per specificare una maschera di accesso per l'oggetto, utilizzare la funzione CreateMutexEx .

Sintassi

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

Parametri

[in, optional] lpMutexAttributes

Puntatore a una struttura SECURITY_ATTRIBUTES . Se questo parametro è NULL, l'handle non può essere ereditato dai processi figlio.

Il membro lpSecurityDescriptor della struttura specifica un descrittore di sicurezza per il nuovo mutex. Se lpMutexAttributes è NULL, il mutex ottiene un descrittore di sicurezza predefinito. Gli ACL nel descrittore di sicurezza predefinito per un mutex provengono dal token primario o di rappresentazione del creatore. Per altre informazioni, vedere Synchronization Object Security and Access Rights.For more information, see Synchronization Object Security and Access Rights.

[in] bInitialOwner

Se questo valore è TRUE e il chiamante ha creato il mutex, il thread chiamante ottiene la proprietà iniziale dell'oggetto mutex. In caso contrario, il thread chiamante non ottiene la proprietà del mutex. Per determinare se il chiamante ha creato il mutex, vedere la sezione Valori restituiti.

[in, optional] lpName

Nome dell'oggetto mutex. Il nome è limitato a MAX_PATH caratteri. Il confronto tra nomi fa distinzione tra maiuscole e minuscole.

Se lpName corrisponde al nome di un oggetto mutex denominato esistente, questa funzione richiede il diritto di accesso MUTEX_ALL_ACCESS . In questo caso, il parametro bInitialOwner viene ignorato perché è già stato impostato dal processo di creazione. Se il parametro lpMutexAttributes non è NULL, determina se l'handle può essere ereditato, ma il relativo membro del descrittore di sicurezza viene ignorato.

Se lpName è NULL, l'oggetto mutex viene creato senza un nome.

Se lpName corrisponde al nome di un evento esistente, semaforo, timer waitable, processo o oggetto di mapping di file, la funzione ha esito negativo e la funzione GetLastError restituisce ERROR_INVALID_HANDLE. Ciò si verifica perché questi oggetti condividono lo stesso spazio dei nomi.

Il nome può avere un prefisso "Global" o "Local" per creare in modo esplicito l'oggetto nello spazio dei nomi globale o sessione. Il resto del nome può contenere qualsiasi carattere ad eccezione del carattere barra rovesciata (\). Per altre informazioni, vedere Spazi dei nomi degli oggetti kernel. Il passaggio rapido degli utenti viene implementato usando le sessioni di Servizi terminal. I nomi degli oggetti kernel devono seguire le linee guida descritte per Servizi terminal in modo che le applicazioni possano supportare più utenti.

L'oggetto può essere creato in uno spazio dei nomi privato. Per altre informazioni, vedere Spazi dei nomi degli oggetti.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per l'oggetto mutex appena creato.

Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Se il mutex è un mutex denominato e l'oggetto esiste prima di questa chiamata di funzione, il valore restituito è un handle per l'oggetto esistente e la funzione GetLastError restituisce ERROR_ALREADY_EXISTS.

Commenti

L'handle restituito da CreateMutex ha il diritto di accesso MUTEX_ALL_ACCESS ; può essere usato in qualsiasi funzione che richiede un handle per un oggetto mutex, a condizione che al chiamante sia stato concesso l'accesso. Se un mutex viene creato da un servizio o da un thread che rappresenta un utente diverso, è possibile applicare un descrittore di sicurezza al mutex quando lo si crea oppure modificare il descrittore di sicurezza predefinito per il processo di creazione modificando il relativo DACL predefinito. Per altre informazioni, vedere Synchronization Object Security and Access Rights.For more information, see Synchronization Object Security and Access Rights.

Se si usa un mutex denominato per limitare l'applicazione a una singola istanza, un utente malintenzionato può creare questo mutex prima di eseguire e impedire l'avvio dell'applicazione. Per evitare questa situazione, creare un mutex denominato in modo casuale e archiviare il nome in modo che possa essere ottenuto solo da un utente autorizzato. In alternativa, è possibile usare un file a questo scopo. Per limitare l'applicazione a un'istanza per utente, creare un file bloccato nella directory del profilo dell'utente.

Qualsiasi thread del processo chiamante può specificare l'handle mutex-object in una chiamata a una delle funzioni di attesa. Le funzioni di attesa a oggetto singolo restituiscono quando viene segnalato lo stato dell'oggetto specificato. È possibile indicare alle funzioni di attesa a più oggetti di restituire quando uno o quando tutti gli oggetti specificati vengono indicati. Quando viene restituita una funzione di attesa, il thread in attesa viene rilasciato per continuare l'esecuzione.

Lo stato di un oggetto mutex viene segnalato quando non è di proprietà di alcun thread. Il thread di creazione può usare il flag bInitialOwner per richiedere la proprietà immediata del mutex. In caso contrario, un thread deve usare una delle funzioni di attesa per richiedere la proprietà. Quando viene segnalato lo stato del mutex, a un thread in attesa viene concessa la proprietà, lo stato del mutex viene modificato in non assegnato e la funzione wait restituisce. Un solo thread può possedere un mutex in qualsiasi momento. Il thread proprietario usa la funzione ReleaseMutex per rilasciarne la proprietà.

Il thread proprietario di un mutex può specificare lo stesso mutex nelle chiamate di funzione di attesa ripetute senza bloccarne l'esecuzione. In genere, non è necessario attendere ripetutamente lo stesso mutex, ma questo meccanismo impedisce a un thread di bloccarsi durante l'attesa di un mutex già proprietario. Tuttavia, per rilasciarne la proprietà, il thread deve chiamare ReleaseMutex una volta per ogni volta che il mutex ha soddisfatto un'attesa.

Due o più processi possono chiamare CreateMutex per creare lo stesso mutex denominato. Il primo processo crea effettivamente il mutex e i processi successivi con diritti di accesso sufficienti aprono semplicemente un handle al mutex esistente. Ciò consente a più processi di ottenere handle dello stesso mutex, garantendo al tempo stesso all'utente la responsabilità di garantire che il processo di creazione venga avviato per primo. Quando si usa questa tecnica, è necessario impostare il flag bInitialOwner su FALSE; in caso contrario, può essere difficile essere certi del processo con proprietà iniziale.

Più processi possono avere handle dello stesso oggetto mutex, consentendo l'uso dell'oggetto per la sincronizzazione interprocesso. Sono disponibili i meccanismi di condivisione degli oggetti seguenti:

  • Un processo figlio creato dalla funzione CreateProcess può ereditare un handle a un oggetto mutex se il parametro lpMutexAttributes dell'ereditarietà abilitata per CreateMutex . Questo meccanismo funziona sia per i mutex denominati che per i mutex senza nome.
  • Un processo può specificare l'handle di un oggetto mutex in una chiamata alla funzione DuplicateHandle per creare un handle duplicato che può essere usato da un altro processo. Questo meccanismo funziona sia per i mutex denominati che per i mutex senza nome.
  • Un processo può specificare un mutex denominato in una chiamata a [OpenMutex](./nf-synchapi-openmutexw.md) o CreateMutex per recuperare un handle per l'oggetto mutex.
Usare la funzione CloseHandle per chiudere l'handle. Il sistema chiude automaticamente l'handle al termine del processo. L'oggetto mutex viene eliminato definitivamente quando l'ultimo handle è stato chiuso.

Esempio

Per un esempio di CreateMutex, vedere Uso di oggetti Mutex.

Nota

L'intestazione synchapi.h definisce CreateMutex come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

   
Client minimo supportato Windows XP [app desktop | App UWP]
Server minimo supportato Windows Server 2003 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione synchapi.h (include Windows.h in Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Libreria Kernel32.lib
DLL Kernel32.dll

Vedere anche

Closehandle

CreateMutexEx

CreateProcess

DuplicateHandle

Oggetti Mutex

Nomi degli oggetti

OpenMutex

Releasemutex

SECURITY_ATTRIBUTES

Funzioni di sincronizzazione