_searchenv_s, _wsearchenv_s

Articolo
03/26/2013

Ricerca di un file utilizzando percorsi dell'ambiente.Queste sono versioni di _searchenv, _wsearchenv con i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

Importante
Questa API non può essere utilizzata nelle applicazioni che vengono eseguite in Windows Runtime.Per ulteriori informazioni, vedere Funzioni CRT non supportate con /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

Parametri

[in] filename
Nome del file da cercare.
[in] varname
Ambiente da cercare.
[out] pathname
Buffer per archiviare il percorso completo.
[in] numberOfElements
Dimensione del buffer di pathname.

Valore restituito

Zero se ha esito positivo; un codice di errore in caso di errore.

Se filename è una stringa vuota, il valore restituito è ENOENT.

Condizioni di errore

filename	varname	pathname	numberOfElements	Valore restituito	Contenuti di pathname.
any	any	NULL	any	EINVAL	n/d
NULL	any	any	any	EINVAL	non modificato
any	any	any	<= 0	EINVAL	non modificato

Se una qualsiasi di queste condizioni di errore caso, il gestore non valido di parametro viene richiamato, come descritto in Convalida dei parametri.Se l'esecuzione può continuare, queste funzioni impostano errno a EINVAL e restituiscono EINVAL.

Note

La routine di _searchenv_s trova il file di destinazione nel dominio specificato.La variabile di varname può essere qualsiasi ambiente o variabile definita dall'utente che specifica un elenco di percorsi di directory, come PATH, LIBe INCLUDE.Poiché _searchenv_s viene fatta distinzione tra maiuscole e minuscole, varname deve corrispondere al caso della variabile.Se varname non corrisponde al nome di una variabile di ambiente definita nell'ambiente del processo, la funzione restituisce zero e la variabile di pathname resterà invariata.

La routine cerca innanzitutto il file nella cartella di lavoro corrente.Se non trova il file, cerca quindi nelle directory specificate dalla variabile di ambiente.Se il file di destinazione è in una delle directory, il percorso appena creato verrà copiato in pathname.Se il file di filename non viene trovato, pathname contiene una stringa con terminazione null vuota.

Il buffer di pathname deve essere almeno caratteri di _MAX_PATH tempo per adattare di integrale il nome del percorso costruito.In caso contrario, _searchenv_s potrebbe sovraccarico del buffer di pathname con un comportamento imprevisto.

_wsearchenv_s è una versione a caratteri estesi di _searchenv_s; gli argomenti a _wsearchenv_s sono stringhe di caratteri estesi._wsearchenv_s e _searchenv_s si comportano in modo identico in caso contrario.

In C++, l'utilizzo di queste funzioni è semplificato dagli overload dei modelli; gli overload possono dedurre la lunghezza del buffer automaticamente (che elimina la necessità di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni precedenti, quelle non sicure alle più recenti e le controparti sicure.Per ulteriori informazioni, vedere Assicurarsi che gli overload del modello.

Mapping di routine a Testo generico

Routine Tchar.h	_UNICODE e _MBCS non definiti	_MBCS definito	_UNICODE definito
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Requisiti

Routine	Intestazione obbligatoria
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> o <wchar.h>

Per ulteriori informazioni sulla compatibilità, vedere Compatibilità nell'introduzione.

Esempio

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