_searchenv_s, _wsearchenv_s

Cerca un file usando i percorsi di ambiente. Queste versioni di hanno _wsearchenvmiglioramenti per_searchenv la sicurezza, come descritto in Funzionalità di sicurezza in CRT.

Importante

Non è possibile usare questa API nelle applicazioni eseguite in Windows Runtime. Per altre informazioni, vedere Funzioni CRT non supportate nelle app della piattaforma UWP (Universal Windows Platform).

Sintassi

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

filename
Nome del file di cui eseguire la ricerca.

varname
Ambiente per la ricerca.

pathname
Buffer per l'archiviazione del percorso completo.

numberOfElements
Dimensioni del pathname buffer.

Valore restituito

Zero se con 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	Contenuto di pathname
qualsiasi	qualsiasi	NULL	qualsiasi	EINVAL	n/d
NULL	qualsiasi	qualsiasi	qualsiasi	EINVAL	non modificato
qualsiasi	qualsiasi	qualsiasi	<=0	EINVAL	non modificato

Se si verifica una di queste condizioni di errore, viene richiamato il gestore di parametri non validi, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, queste funzioni impostano errno su EINVAL e restituiscono EINVAL.

Osservazioni:

La routine _searchenv_s cerca il file di destinazione nel dominio specifico. La variabile varname può essere qualsiasi variabile di ambiente o variabile definita dall'utente, che specifica un elenco dei percorsi di directory, come PATH, LIB e INCLUDE. Poiché _searchenv_s fa distinzione tra maiuscole e minuscole, varname deve corrispondere alle maiuscole e minuscole della variabile d'ambiente. Se varname non corrisponde al nome di una variabile di ambiente definita nell'ambiente del processo, la funzione restituisce zero e la pathname variabile rimane invariata.

La routine cerca innanzitutto il file nella directory di lavoro corrente. Se il file non viene trovato, la ricerca viene eseguita nelle directory specificate dalla variabile di ambiente. Se il file di destinazione si trova in una di queste directory, il percorso appena creato viene copiato in pathname. Se il filename file non viene trovato, pathname contiene una stringa vuota con terminazione Null.

Il buffer pathname deve contenere almeno _MAX_PATH caratteri per consentire tutta la lunghezza del nome percorso completo. In alternativa, _searchenv_s potrebbe sovraccaricare il buffer pathname e causare un comportamento imprevisto.

_wsearchenv_s è una versione a caratteri "wide" di _searchenv_s. Gli argomenti per _wsearchenv_s sono stringhe a caratteri "wide". In caso contrario,_wsearchenv_s e _searchenv_s si comportano in modo identico.

In C++ l'utilizzo di queste funzioni è semplificato dagli overload dei modelli. Gli overload possono dedurre la lunghezza del buffer automaticamente (eliminando la necessità di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni precedenti e non sicure con le controparti più recenti e sicure. Per altre informazioni, vedere Proteggere gli overload dei modelli.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Mapping di routine di testo generico

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

Requisiti

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

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

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

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

Vedi anche

Controllo directory
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv