Funzione SearchPathA (processenv.h)

Articolo
11/20/2024

Cerca un file specificato in un percorso specificato.

Sintassi

DWORD SearchPathA(
  [in, optional]  LPCSTR lpPath,
  [in]            LPCSTR lpFileName,
  [in, optional]  LPCSTR lpExtension,
  [in]            DWORD  nBufferLength,
  [out]           LPSTR  lpBuffer,
  [out, optional] LPSTR  *lpFilePart
);

Parametri

[in, optional] lpPath

Percorso in cui cercare il file.

Se questo parametro è NULL, la funzione cerca un file corrispondente usando un percorso di ricerca del sistema dipendente dal Registro di sistema. Per altre informazioni, vedere la sezione Osservazioni.

[in] lpFileName

Nome del file in cui eseguire la ricerca.

Per impostazione predefinita, il nome è limitato a MAX_PATH caratteri. Per estendere questo limite a 32.767 caratteri wide, anteporre "\\?\" al percorso. Per altre informazioni, vedere denominazione di file, percorsi e spazi dei nomi.

Mancia

A partire da Windows 10, versione 1607, è possibile acconsentire esplicitamente alla rimozione della limitazione MAX_PATH senza anteporre "\\?\". Per informazioni dettagliate, vedere la sezione "Limitazione massima della lunghezza del percorso" di nomi, percorsi e spazi dei nomi.

[in, optional] lpExtension

Estensione da aggiungere al nome del file durante la ricerca del file. Il primo carattere dell'estensione del nome file deve essere un punto (.). L'estensione viene aggiunta solo se il nome file specificato non termina con un'estensione.

Se un'estensione di file non è necessaria o se il nome file contiene un'estensione, questo parametro può essere NULL.

[in] nBufferLength

Dimensioni del buffer che riceve il percorso e il nome file validi (incluso il carattere Null di terminazione), in TCHAR.

[out] lpBuffer

Puntatore al buffer per ricevere il percorso e il nome file del file trovato. La stringa è una stringa con terminazione Null.

[out, optional] lpFilePart

Puntatore alla variabile per ricevere l'indirizzo (all'interno di lpBuffer) dell'ultimo componente del percorso e del nome file validi, ovvero l'indirizzo del carattere immediatamente successivo alla barra rovesciata finale (\) nel percorso.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è la lunghezza, in TCHARs, della stringa copiata nel buffer, senza includere il carattere Null di terminazione. Se il valore restituito è maggiore di nBufferLength, il valore restituito è la dimensione del buffer necessario per contenere il percorso, incluso il carattere Null di terminazione.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

Se il parametro lpPath è NULL, SearchPath cerca un file corrispondente in base al valore corrente del Registro di sistema seguente:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SafeProcessSearchMode

Quando il valore di questo REG_DWORD valore del Registro di sistema è impostato su 1, SearchPath prima cerca le cartelle specificate nel percorso di sistema e quindi cerca nella cartella di lavoro corrente. Quando il valore di questo valore del Registro di sistema è impostato su 0, il computer cerca innanzitutto la cartella di lavoro corrente e quindi cerca le cartelle specificate nel percorso di sistema. Il valore predefinito del sistema per questa chiave del Registro di sistema è 0.

La modalità di ricerca usata dalla funzione SearchPath può essere impostata anche per processo chiamando la funzione SetSearchPathMode.

La funzione SearchPath non è consigliata come metodo di individuazione di un file .dll se l'uso previsto dell'output è in una chiamata alla funzione LoadLibrary . Ciò può comportare l'individuazione del file di .dll errato perché l'ordine di ricerca della funzione SearchPath differisce dall'ordine di ricerca usato dalla funzione LoadLibrary . Se è necessario individuare e caricare un file .dll, usare la funzione loadLibrary .

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Sostenuto
Protocollo SMB (Server Message Block) 3.0	Sì
SMB 3.0 Transparent Failover (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
Cluster Shared Volume File System (CsvFS)	Sì
Resilient File System (ReFS)	Sì

Nota

L'intestazione processenv.h definisce SearchPath 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 [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	processenv.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll