_searchenv_s, _wsearchenv_s

 

Pour obtenir la dernière documentation sur Visual Studio 2017 RC, consultez Documentation Visual Studio 2017 RC.

Recherche un fichier en utilisant les chemins d'environnement. Ces versions de _searchenv, _wsearchenv présentent des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.

System_CAPS_ICON_important.jpg Important

Cette API ne peut pas être utilisée dans les applications qui s'exécutent dans le Windows Runtime. Pour plus d'informations, consultez Fonctions CRT non prises en charge avec /ZW.

errno_t _searchenv_s(  
   const char *filename,  
   const char *varname,  
   char *pathname,  
   size_t numberOfElements  
);  
errno_t _wsearchenv_s(  
   const wchar_t *filename,  
   const wchar_t *varname,  
   wchar_t *pathname,  
   size_t numberOfElements  
);  
template <size_t size>  
errno_t _searchenv_s(  
   const char *filename,  
   const char *varname,  
   char (&pathname)[size]  
); // C++ only  
template <size_t size>  
errno_t _wsearchenv_s(  
   const wchar_t *filename,  
   const wchar_t *varname,  
   wchar_t (&pathname)[size]  
); // C++ only  

Paramètres

[in] filename
Nom du fichier à rechercher.

[in] varname
Environnement dans lequel chercher.

[out] pathname
Mémoire tampon pour stocker le chemin d'accès complet.

[in] numberOfElements
Taille de la mémoire tampon pour pathname.

Zéro si l'opération a réussi ; code d'erreur en cas de échec.

Si filename est une chaîne de caractères vide, la valeur de retour est ENOENT.

Conditions d'erreur

filenamevarnamepathnamenumberOfElementsValeur de retourContenu de pathname.
anyanyNULLanyEINVALN/A
NULLanyanyanyEINVALnon modifié
anyanyany<= 0EINVALnon modifié

Si l'une de ces conditions d'erreur se produit, le gestionnaire de paramètre non valide est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, ces fonctions définissent errno à la valeur EINVAL et retournent EINVAL.

La routine _searchenv_s recherche le fichier cible dans le domaine spécifié. La variable varname peut être tout environnement ou variable définie par l'utilisateur qui spécifie une liste de chemins d'accès aux répertoires, tels que PATH, LIB, et INCLUDE. Comme _searchenv_s respecte la casse, varname doit correspondre à la casse de la variable d'environnement. Si varname ne correspond pas au nom d'une variable d'environnement définie dans l'environnement du processus, la fonction retourne zéro et la variable pathname reste inchangée.

La routine recherche d'abord le fichier dans le répertoire de travail actuel. Si elle ne trouve pas le fichier, elle parcourt ensuite les répertoires spécifiés par la variable d'environnement. Si le fichier cible est dans un de ces répertoires, le chemin d'accès nouvellement créé est copié dans pathname. Si le fichier filename est introuvable, pathname contient une chaîne vide terminée par le caractère NULL.

La mémoire tampon pathname doit être longue d'au moins _MAX_PATH caractères afin de pouvoir contenir le chemin d'accès construit en entier. Sinon, _searchenv_s pourrait provoquer un dépassement de mémoire tampon depathname ce qui occasionnerait un comportement imprévisible.

_wsearchenv_s est une version à caractères larges de _searchenv_s ; les arguments vers _wsearchenv_s sont des chaînes à caractères larges. _wsearchenv_s et _searchenv_s se comportent sinon de manière identique.

En C++, l'utilisation de ces fonctions est simplifiée par les surcharges de modèle ; les surcharges peuvent déduire la longueur de la mémoire tampon automatiquement (ce qui évite d'avoir à spécifier un argument taille) et peuvent remplacer automatiquement les fonctions plus anciennes et non sécurisées par leurs équivalentes plus récentes et sécurisées. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

Mappages de routines de texte générique

Routine Tchar.h_UNICODE et _MBCS non définis_MBCS défini_UNICODE défini
_tsearchenv_s_searchenv_s_searchenv_s_wsearchenv_s
RoutineEn-tête requis
_searchenv_s<stdlib.h>
_wsearchenv_s<stdlib.h> ou <wchar.h>

Pour plus d'informations sur la compatibilité, consultez Compatibilité.

// crt_searchenv_s.c  
/* This program searches for a file in  
 * a directory specified by an environment variable.  
 */  
  
#include <stdlib.h>  
#include <stdio.h>  
  
int main( void )  
{  
   char pathbuffer[_MAX_PATH];  
   char searchfile[] = "CL.EXE";  
   char envvar[] = "PATH";  
   errno_t err;  
  
   /* Search for file in PATH environment variable: */  
   err = _searchenv_s( searchfile, envvar, pathbuffer, _MAX_PATH );  
   if (err != 0)  
   {  
      printf("Error searching the path. Error code: %d\n", err);  
   }  
   if( *pathbuffer != '\0' )  
      printf( "Path for %s:\n%s\n", searchfile, pathbuffer );  
   else  
      printf( "%s not found\n", searchfile );  
}  

Chemin d'accès pour CL.EXE :
C:\Program Files\Microsoft Visual Studio 2010\VC\BIN\CL.EXE

Non applicable. Pour appeler la fonction C standard, utilisez PInvoke. Pour plus d'informations, consultez Exemples d'appel de plateforme.

Contrôle de répertoire
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv

Afficher: