_searchenv_s, _wsearchenv_s

Recherche un fichier en utilisant des chemins d’environnement. Ces versions ont des améliorations de _searchenv _wsearchenvsécurité, comme décrit dans les fonctionnalités de sécurité du CRT.

Syntaxe

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

filename
Nom du fichier à rechercher.

varname
Environnement dans lequel effectuer la recherche.

pathname
Mémoire tampon destinée à stocker le chemin d’accès complet.

numberOfElements
Taille de la pathname mémoire tampon.

Valeur retournée

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

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

Conditions d’erreur

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

Notes

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

La routine recherche d’abord le fichier dans le répertoire de travail actif. S’il ne trouve pas le fichier, il examine ensuite les répertoires spécifiés par la variable d’environnement. Si le fichier cible se trouve dans l'un de ces répertoires, le chemin d'accès qui vient d'être créé est copié dans pathname. Si le filename fichier est introuvable, pathname contient une chaîne vide terminée par null.

La mémoire tampon pathname doit faire une longueur minimale de _MAX_PATH caractères pour loger le nom de chemin d'accès construit dans son intégralité. Sinon, _searchenv_s risque de saturer la mémoire tampon pathname et occasionner un comportement inattendu.

_wsearchenv_s est une version à caractères larges de _searchenv_s; les arguments de _wsearchenv_s sont des chaînes à caractères larges. Sinon,_wsearchenv_s et _searchenv_s se comportent de la même façon.

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.

Par défaut, l’état global de cette fonction est limité à l’application. Pour modifier ce comportement, consultez État global dans le CRT.

Mappages de routines de texte générique

Spécifications

Pour plus d’informations sur la compatibilité, consultez Compatibility.

Exemple

// 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 );
}

Path for CL.EXE:
C:\Program Files\Microsoft Visual Studio 2010\VC\BIN\CL.EXE

Voir aussi

Contrôle d’annuaire
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv