_searchenv_s, _wsearchenv_s

Article
03/26/2013

Recherche un fichier à l'aide de les chemins d'environnement.Ce sont des versions d' _searchenv, _wsearchenv avec des améliorations de sécurité comme décrit dans Fonctionnalités de sécurité du CRT.

Important

Cette API ne peut pas être utilisée dans les applications qui s'exécutent dans les fenêtres d'exécution.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 à rechercher.
[out] pathname
Mémoire tampon pour stocker le chemin d'accès complet.
[in] numberOfElements
Taille de la mémoire tampon d' pathname.

Valeur de retour

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

filename	varname	pathname	numberOfElements	Valeur de retour	Contenu d' pathname
any	any	NULL	any	EINVAL	N/A
NULL	any	any	any	EINVAL	non modifié
any	any	any	<= 0	EINVAL	non modifié

Si l'un de ces conditions d'erreur se produit, le gestionnaire de paramètre non valide est appelé, comme décrit dans Validation des paramètres.Si est autorisé à l'exécution pour continuer, ces errno défini par fonctions à EINVAL et à EINVALde retour.

Notes

Les recherches de routine d' _searchenv_s pour le fichier cible dans le champ spécifié.La variable d' varname peut être tout environnement ou variable définie par l'utilisateur qui spécifie une liste de chemins d'accès du répertoire, tels qu' PATH, LIB, et INCLUDE.Étant donné qu' _searchenv_s respecte la casse, varname doit correspondre le cas 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 d' pathname reste inchangée.

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

La mémoire tampon d' pathname doit être au moins des caractères d' _MAX_PATH de temps pour s'adapter à l'entier le chemin d'accès construit.Sinon, _searchenv_s peut provoquer un mémoire tampon d' pathname ce qui peut provoquer un comportement inattendu.

_wsearchenv_s est une version à caractère élargi d' _searchenv_s; les arguments à _wsearchenv_s sont des chaînes à caractères larges._wsearchenv_s et _searchenv_s se comportent de sinon.

En C++, l'utilisation de ces fonctions est simplifié par des surcharges de modèle ; les surcharges peuvent également déduire la longueur de la mémoire tampon automatiquement (éliminant le besoin de spécifier un argument de taille) et peuvent remplacer automatiquement des fonctions plus anciennes et non sécurisées par leurs nouvelles, sécurisées équivalents.Pour plus d'informations, consultez Surcharges sécurisées de modèle.

Mappages de routines de texte générique

Routine de Tchar.h	_UNICODE et non définis _MBCS	_MBCS défini	_UNICODE défini
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Configuration requise

Routine	En-tête requis
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> ou <wchar.h>

Pour plus d'informations de compatibilité, consultez l' Compatibilité dans l'introduction.

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