Fonction SearchPathA (processenv.h)

Article
11/20/2024

Recherche un fichier spécifié dans un chemin d’accès spécifié.

Syntaxe

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

Paramètres

[in, optional] lpPath

Chemin d’accès à rechercher dans le fichier.

Si ce paramètre est NULL, la fonction recherche un fichier correspondant à l’aide d’un chemin de recherche système dépendant du Registre. Pour plus d’informations, consultez la section Remarques.

[in] lpFileName

Nom du fichier pour lequel effectuer une recherche.

Par défaut, le nom est limité à MAX_PATH caractères. Pour étendre cette limite à 32 767 caractères larges, ajoutez « \\ ?\ » au chemin d’accès. Pour plus d’informations, consultez nommage des fichiers, des chemins d’accès et des espaces de noms.

Pourboire

À compter de Windows 10, version 1607, vous pouvez choisir de supprimer la limitation MAX_PATH sans précéder « \\ ?\ ». Pour plus d’informations, consultez la section « Limite maximale de longueur de chemin » de noms, fichiers, chemin s et espaces de noms.

[in, optional] lpExtension

Extension à ajouter au nom du fichier lors de la recherche du fichier. Le premier caractère de l’extension de nom de fichier doit être un point (.). L’extension est ajoutée uniquement si le nom de fichier spécifié ne se termine pas par une extension.

Si une extension de nom de fichier n’est pas requise ou si le nom de fichier contient une extension, ce paramètre peut être NULL.

[in] nBufferLength

Taille de la mémoire tampon qui reçoit le chemin d’accès et le nom de fichier valides (y compris le caractère null de fin), dans TCHAR.

[out] lpBuffer

Pointeur vers la mémoire tampon pour recevoir le chemin d’accès et le nom de fichier du fichier trouvé. La chaîne est une chaîne terminée par null.

[out, optional] lpFilePart

Pointeur vers la variable pour recevoir l’adresse (dans lpBuffer) du dernier composant du chemin d’accès valide et du nom de fichier, qui est l’adresse du caractère immédiatement après la barre oblique inverse finale (\) dans le chemin.

Valeur de retour

Si la fonction réussit, la valeur retournée est la longueur, dans TCHAR, de la chaîne copiée dans la mémoire tampon, sans inclure le caractère null de fin. Si la valeur de retour est supérieure à nBufferLength, la valeur retournée est la taille de la mémoire tampon requise pour contenir le chemin, y compris le caractère null de fin.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError.

Remarques

Si le paramètre lpPath est NULL, SearchPath recherche un fichier correspondant en fonction de la valeur actuelle de la valeur de Registre suivante :

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

Lorsque la valeur de cette valeur de Registre REG_DWORD est définie sur 1, SearchPath recherche d’abord les dossiers spécifiés dans le chemin d’accès système, puis recherche le dossier de travail actif. Lorsque la valeur de cette valeur de Registre est définie sur 0, l’ordinateur recherche d’abord le dossier de travail actuel, puis recherche les dossiers spécifiés dans le chemin d’accès système. La valeur par défaut système de cette clé de Registre est 0.

Le mode de recherche utilisé par la fonction SearchPath peut également être défini par processus en appelant la fonction SetSearchPathMode.

La fonction SearchPath n’est pas recommandée comme méthode de localisation d’un fichier .dll si l’utilisation prévue de la sortie se trouve dans un appel à la fonction LoadLibrary. Cela peut entraîner la localisation du fichier .dll incorrect, car l’ordre de recherche de la fonction SearchPath diffère de l’ordre de recherche utilisé par la fonction LoadLibrary. Si vous devez localiser et charger un fichier .dll, utilisez la fonction LoadLibrary.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Supporté
Protocole SMB (Server Message Block) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Oui
Cluster Shared Volume File System (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Note

L’en-tête processenv.h définit SearchPath 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 uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	processenv.h (include Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll