Funzione CreateProcessA (processthreadsapi.h)
Crea un nuovo processo e il relativo thread primario. Il nuovo processo viene eseguito nel contesto di sicurezza del processo chiamante.
Se il processo chiamante rappresenta un altro utente, il nuovo processo usa il token per il processo chiamante, non il token di rappresentazione. Per eseguire il nuovo processo nel contesto di sicurezza dell'utente rappresentato dal token di rappresentazione, usare la funzione CreateProcessAsUserA o funzione CreateProcessWithLogonW.
Sintassi
BOOL CreateProcessA(
[in, optional] LPCSTR lpApplicationName,
[in, out, optional] LPSTR lpCommandLine,
[in, optional] LPSECURITY_ATTRIBUTES lpProcessAttributes,
[in, optional] LPSECURITY_ATTRIBUTES lpThreadAttributes,
[in] BOOL bInheritHandles,
[in] DWORD dwCreationFlags,
[in, optional] LPVOID lpEnvironment,
[in, optional] LPCSTR lpCurrentDirectory,
[in] LPSTARTUPINFOA lpStartupInfo,
[out] LPPROCESS_INFORMATION lpProcessInformation
);
Parametri
[in, optional] lpApplicationName
Nome del modulo da eseguire. Questo modulo può essere un'applicazione basata su Windows. Può trattarsi di un altro tipo di modulo (ad esempio, MS-DOS o OS/2) se il sottosistema appropriato è disponibile nel computer locale.
La stringa può specificare il percorso completo e il nome file del modulo da eseguire oppure può specificare un nome parziale. Nel caso di un nome parziale, la funzione usa l'unità corrente e la directory corrente per completare la specifica. La funzione non userà il percorso di ricerca. Questo parametro deve includere l'estensione del nome file; non si presuppone alcuna estensione predefinita.
Il parametro lpApplicationName
- c:\program.exe
- c:\program files\sub.exe
- c:\program files\sub dir\program.exe
- c:\program files\sub dir\program name.exe
Se il modulo eseguibile è un'applicazione a 16 bit, lpApplicationName deve essere NULLe la stringa a cui punta lpCommandLine deve specificare il modulo eseguibile e i relativi argomenti.
Per eseguire un file batch, è necessario avviare l'interprete dei comandi; impostare lpApplicationName su cmd.exe e impostare lpCommandLine agli argomenti seguenti: /c più il nome del file batch.
Importante
Il team di progettazione MSRC consiglia di farlo. Per altri dettagli, vedere MS14-019 - Correzione di un hijack binario tramite .cmd o .bat file.
[in, out, optional] lpCommandLine
Riga di comando da eseguire.
La lunghezza massima di questa stringa è di 32.767 caratteri, incluso il carattere Null di terminazione Unicode. Se lpApplicationName è NULL, la parte relativa al nome del modulo di lpCommandLine è limitata ai caratteri MAX_PATH.
La versione Unicode di questa funzione, CreateProcessW, può modificare il contenuto di questa stringa. Pertanto, questo parametro non può essere un puntatore alla memoria di sola lettura, ad esempio una const variabile o una stringa letterale. Se questo parametro è una stringa costante, la funzione può causare una violazione di accesso.
Il parametro lpCommandLine può essere NULL. In tal caso, la funzione usa la stringa a cui punta lpApplicationName come riga di comando.
Se sia lpApplicationName che lpCommandLine non sononull, la stringa con terminazione Null a cui punta lpApplicationName specifica il modulo da eseguire e la stringa con terminazione Null a cui punta lpCommandLine specifica la riga di comando. Il nuovo processo può usare GetCommandLine per recuperare l'intera riga di comando. I processi della console scritti in C possono usare gli argomenti argc
Se lpApplicationName è NULL, il primo token delimitato da spazi vuoti della riga di comando specifica il nome del modulo. Se si usa un nome di file lungo contenente uno spazio, usare le stringhe tra virgolette per indicare dove termina il nome del file e gli argomenti iniziano (vedere la spiegazione per il parametro lpApplicationName). Se il nome file non contiene un'estensione, .exe viene accodato. Pertanto, se l'estensione del nome file è .com, questo parametro deve includere l'estensione .com. Se il nome del file termina con un punto (.) senza estensione o se il nome del file contiene un percorso, .exe non viene accodato. Se il nome del file non contiene un percorso di directory, il sistema cerca il file eseguibile nella sequenza seguente:
- Directory da cui è stata caricata l'applicazione.
- Directory corrente per il processo padre.
- Directory di sistema Windows a 32 bit. Usare la funzione GetSystemDirectoryA per ottenere il percorso di questa directory.
- Directory di sistema Windows a 16 bit. Non esiste alcuna funzione che ottiene il percorso di questa directory, ma viene eseguita la ricerca. Il nome di questa directory è System.
- Directory di Windows. Usare la funzione GetWindowsDirectoryA per ottenere il percorso di questa directory.
- Directory elencate nella variabile di ambiente PATH. Si noti che questa funzione non esegue ricerche nel percorso per applicazione specificato dalla Percorsi app chiave del Registro di sistema. Per includere questo percorso per applicazione nella sequenza di ricerca, usare la funzione ShellExecute.
Il sistema aggiunge un carattere Null di terminazione alla stringa della riga di comando per separare il nome file dagli argomenti. In questo modo la stringa originale viene divisa in due stringhe per l'elaborazione interna.
[in, optional] lpProcessAttributes
Puntatore a una struttura SECURITY_ATTRIBUTES che determina se l'handle restituito al nuovo oggetto processo può essere ereditato dai processi figlio. Se lpProcessAttributes è NULL, l'handle non può essere ereditato.
Il lpSecurityDescriptor membro della struttura specifica un descrittore di sicurezza per il nuovo processo. Se lpProcessAttributes è NULL o lpSecurityDescriptor è NULL, il processo ottiene un descrittore di sicurezza predefinito. Gli ACL nel descrittore di sicurezza predefinito per un processo provengono dal token primario dell'autore. Windows XP: Gli elenchi di controllo di accesso nel descrittore di sicurezza predefinito per un processo provengono dal token primario o di rappresentazione dell'autore. Questo comportamento è cambiato con Windows XP con SP2 e Windows Server 2003.
[in, optional] lpThreadAttributes
Puntatore a una struttura SECURITY_ATTRIBUTES che determina se l'handle restituito al nuovo oggetto thread può essere ereditato dai processi figlio. Se lpThreadAttributes è NULL, l'handle non può essere ereditato.
Il lpSecurityDescriptor membro della struttura specifica un descrittore di sicurezza per il thread principale. Se lpThreadAttributes è NULL o lpSecurityDescriptor è NULL, il thread ottiene un descrittore di sicurezza predefinito. Gli elenchi di controllo di accesso nel descrittore di sicurezza predefinito per un thread provengono dal token di processo. Windows XP: Gli elenchi di controllo di accesso nel descrittore di sicurezza predefinito per un thread provengono dal token primario o di rappresentazione dell'autore. Questo comportamento è cambiato con Windows XP con SP2 e Windows Server 2003.
[in] bInheritHandles
Se questo parametro è TRUE, ogni handle ereditabile nel processo chiamante viene ereditato dal nuovo processo. Se il parametro è FALSE, gli handle non vengono ereditati. Si noti che gli handle ereditati hanno lo stesso valore e gli stessi diritti di accesso degli handle originali. Per altre informazioni sugli handle ereditabili, vedere Osservazioni.
Servizi terminal: Non è possibile ereditare handle tra le sessioni. Inoltre, se questo parametro è TRUE, è necessario creare il processo nella stessa sessione del chiamante.
processi PPL (Protected Process Light): L'ereditarietà dell'handle generico viene bloccata quando un processo PPL crea un processo non PPL poiché PROCESS_DUP_HANDLE non è consentito da un processo non PPL a un processo PPL. Vedere Process Security and Access Rights
Windows 7: STD_INPUT_HANDLE, STD_OUTPUT_HANDLE e STD_ERROR_HANDLE vengono ereditati, anche quando il parametro è FALSE.
[in] dwCreationFlags
Flag che controllano la classe di priorità e la creazione del processo. Per un elenco di valori, vedere flag di creazione di processi .
Questo parametro controlla anche la classe di priorità del nuovo processo, che viene usata per determinare le priorità di pianificazione dei thread del processo. Per un elenco di valori, vedere GetPriorityClass. Se non viene specificato alcun flag di classe di priorità, per impostazione predefinita la classe priority viene NORMAL_PRIORITY_CLASS a meno che la classe di priorità del processo di creazione non sia IDLE_PRIORITY_CLASS o BELOW_NORMAL_PRIORITY_CLASS. In questo caso, il processo figlio riceve la classe di priorità predefinita del processo chiamante.
Se il parametro dwCreationFlags ha un valore pari a 0:
- Il processo eredita sia la modalità di errore del chiamante che la console dell'elemento padre.
- Si presuppone che il blocco di ambiente per il nuovo processo contenga caratteri ANSI (vedere parametro lpEnvironment per altre informazioni).
- Un'applicazione basata su Windows a 16 bit viene eseguita in una macchina DOS virtuale condivisa (VDM).
[in, optional] lpEnvironment
Puntatore al blocco di ambiente per il nuovo processo. Se questo parametro è NULL, il nuovo processo usa l'ambiente del processo chiamante.
Un blocco di ambiente è costituito da un blocco con terminazione Null di stringhe con terminazione Null. Ogni stringa è nel formato seguente:
nome=valore\0
Poiché il segno di uguale viene usato come separatore, non deve essere usato nel nome di una variabile di ambiente.
Un blocco di ambiente può contenere caratteri Unicode o ANSI. Se il blocco di ambiente a cui punta lpEnvironment contiene caratteri Unicode, assicurarsi che dwCreationFlags includa CREATE_UNICODE_ENVIRONMENT.
La versione ANSI di questa funzione CreateProcessA ha esito negativo se le dimensioni totali del blocco di ambiente per il processo superano i 32.767 caratteri.
Si noti che un blocco di ambiente ANSI viene terminato da due byte zero: uno per l'ultima stringa, uno più per terminare il blocco. Un blocco di ambiente Unicode viene terminato da quattro byte zero: due per l'ultima stringa, altre due per terminare il blocco.
[in, optional] lpCurrentDirectory
Percorso completo della directory corrente per il processo. La stringa può anche specificare un percorso UNC.
Se questo parametro è NULL, il nuovo processo avrà la stessa unità corrente e la stessa directory del processo chiamante. Questa funzionalità viene fornita principalmente per le shell che devono avviare un'applicazione e specificare l'unità iniziale e la directory di lavoro.
[in] lpStartupInfo
Puntatore a una struttura STARTUPINFO o STARTUPINFOEX.
Per impostare gli attributi estesi, usare una struttura di STARTUPINFOEX e specificare EXTENDED_STARTUPINFO_PRESENT nel parametro dwCreationFlags.
Gli handle in STARTUPINFO o STARTUPINFOEX devono essere chiusi con CloseHandle quando non sono più necessari.
Importante
Il chiamante è responsabile di garantire che i campi handle standard in STARTUPINFO contengano valori di handle validi. Questi campi vengono copiati invariati nel processo figlio senza convalida, anche quando il membro
[out] lpProcessInformation
Puntatore a una struttura PROCESS_INFORMATION che riceve informazioni di identificazione sul nuovo processo.
Gli handle in PROCESS_INFORMATION devono essere chiusi con CloseHandle quando non sono più necessari.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è diverso da zero.
Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.
Si noti che la funzione restituisce prima che il processo abbia terminato l'inizializzazione. Se non è possibile individuare o non inizializzare una DLL necessaria, il processo viene terminato. Per ottenere lo stato di terminazione di un processo, chiamare GetExitCodeProcess.
Osservazioni
Al processo viene assegnato un identificatore di processo. L'identificatore è valido fino al termine del processo. Può essere usato per identificare il processo o specificato nella funzione OpenProcess per aprire un handle al processo. Al thread iniziale nel processo viene assegnato anche un identificatore di thread. Può essere specificato nella funzione OpenThread per aprire un handle al thread. L'identificatore è valido fino al termine del thread e può essere usato per identificare in modo univoco il thread all'interno del sistema. Questi identificatori vengono restituiti nella struttura PROCESS_INFORMATION.
Il nome dell'eseguibile nella riga di comando fornito dal sistema operativo a un processo non è necessariamente identico a quello fornito dal processo chiamante alla funzione CreateProcess
Il thread chiamante può usare la funzione WaitForInputIdle per attendere il completamento dell'inizializzazione del nuovo processo e attende l'input dell'utente senza input in sospeso. Ciò può essere utile per la sincronizzazione tra processi padre e figlio, perché CreateProcess restituisce senza attendere il completamento dell'inizializzazione del nuovo processo. Ad esempio, il processo di creazione userà WaitForInputIdle prima di cercare una finestra associata al nuovo processo.
Il modo preferito per arrestare un processo consiste nell'usare la funzione ExitProcess
Un processo padre può modificare direttamente le variabili di ambiente di un processo figlio durante la creazione del processo. Questa è l'unica situazione in cui un processo può modificare direttamente le impostazioni di ambiente di un altro processo. Per altre informazioni, vedere Modifica delle variabili di ambiente.
Se un'applicazione fornisce un blocco di ambiente, le informazioni di directory correnti delle unità di sistema non vengono propagate automaticamente al nuovo processo. Ad esempio, esiste una variabile di ambiente denominata =C: il cui valore è la directory corrente nell'unità C. Un'applicazione deve passare manualmente le informazioni sulla directory corrente al nuovo processo. A tale scopo, l'applicazione deve creare in modo esplicito queste stringhe di variabili di ambiente, ordinarle in ordine alfabetico (perché il sistema usa un ambiente ordinato) e inserirle nel blocco di ambiente. In genere, verranno posizionati all'inizio del blocco di ambiente, a causa dell'ordinamento dei blocchi di ambiente.
Un modo per ottenere le informazioni sulla directory corrente per un'unità X consiste nell'effettuare la chiamata seguente: GetFullPathName("X:", ...). In questo modo si evita che un'applicazione abbia la necessità di analizzare il blocco di ambiente. Se il percorso completo restituito è X:, non è necessario passare tale valore come dati di ambiente, poiché la directory radice è la directory corrente predefinita per l'unità X di un nuovo processo.
Quando viene creato un processo con CREATE_NEW_PROCESS_GROUP specificato, viene eseguita una chiamata implicita a SetConsoleCtrlHandler(NULL,TRUE) per conto del nuovo processo; ciò significa che il nuovo processo ha CTRL+C disabilitato. In questo modo, le shell gestiscono autonomamente CTRL+C e passano selettivamente tale segnale a processi secondari. CTRL+INTERR non è disabilitato e può essere usato per interrompere il gruppo di processi/processi.
Per impostazione predefinita, passando TRUE come valore del parametro bInheritHandles fa sì che tutti gli handle ereditabili vengano ereditati dal nuovo processo. Ciò può essere problematico per le applicazioni che creano processi da più thread contemporaneamente, ma desiderano che ogni processo erediti handle diversi.
Le applicazioni possono usare la funzione UpdateProcThreadAttributeList
Osservazioni sulla sicurezza
Il primo parametro, lpApplicationName, può essere NULL, nel qual caso il nome eseguibile deve trovarsi nella stringa delimitata da spazi vuoti a cui punta lpCommandLine. Se il nome del file eseguibile o del percorso contiene uno spazio, esiste il rischio che un eseguibile diverso possa essere eseguito a causa del modo in cui la funzione analizza gli spazi. L'esempio seguente è pericoloso perché la funzione tenterà di eseguire "Program.exe", se esistente, anziché "MyApp.exe".
LPTSTR szCmdline = _tcsdup(TEXT("C:\\Program Files\\MyApp -L -S"));
CreateProcess(NULL, szCmdline, /* ... */);
Se un utente malintenzionato deve creare un'applicazione denominata "Program.exe" in un sistema, qualsiasi programma che chiama erroneamente CreateProcess usando la directory Programmi eseguirà questa applicazione anziché l'applicazione desiderata.
Per evitare questo problema, non passare NULL per lpApplicationName. Se si passa NULL per lpApplicationName, usare le virgolette intorno al percorso eseguibile in lpCommandLine, come illustrato nell'esempio seguente.
LPTSTR szCmdline[] = _tcsdup(TEXT("\"C:\\Program Files\\MyApp\" -L -S"));
CreateProcess(NULL, szCmdline, /*...*/);
Esempi
Per un esempio, vedere Creazione di processi.
Nota
L'intestazione processthreadsapi.h definisce CreateProcess 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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [app desktop | App UWP] |
| server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| piattaforma di destinazione | Finestre |
| intestazione |
processthreadsapi.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 |