_searchenv_s, _wsearchenv_s

Busca un archivo mediante rutas de acceso del entorno. Estas versiones de , _wsearchenvtienen mejoras de_searchenv seguridad, como se describe en Características de seguridad de CRT.

Importante

Esta API no se puede usar en aplicaciones que se ejecutan en Windows en tiempo de ejecución. Para obtener más información, vea Funciones de CRT no admitidas en aplicaciones de la Plataforma universal de Windows.

Sintaxis

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

Parámetros

filename
Nombre del archivo que se va a buscar.

varname
Entorno en el que se va a buscar.

pathname
Búfer en el que se va a almacenar la ruta de acceso completa.

numberOfElements
Tamaño del pathname búfer.

Valor devuelto

Devuelve cero si se ejecuta correctamente; devuelve un código de error si se produce un error.

Si filename es una cadena vacía, el valor devuelto es ENOENT.

Condiciones de error

filename	varname	pathname	numberOfElements	Valor devuelto	Contenido de pathname
cualquiera	cualquiera	NULL	cualquiera	EINVAL	N/D
NULL	cualquiera	cualquiera	cualquiera	EINVAL	no cambia
cualquiera	cualquiera	cualquiera	<= 0	EINVAL	no cambia

Si se produce alguna de estas condiciones de error, se invoca al controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, estas funciones establecen errno en EINVAL y devuelven EINVAL.

Comentarios

Las rutina _searchenv_s busca el archivo de destino en el dominio especificado. La variable varname puede ser cualquier variable de entorno o definida por el usuario que especifique una lista de rutas de acceso de directorio, por ejemplo PATH, LIB y INCLUDE. Dado que _searchenv_s distingue entre mayúsculas y minúsculas, varname debe coincidir con las mayúsculas y minúsculas de la variable de entorno. Si varname no coincide con el nombre de una variable de entorno definida en el entorno del proceso, la función devuelve cero y la pathname variable no cambia.

La rutina busca el archivo primero en el directorio de trabajo actual. Si no encuentra el archivo, se examina junto a los directorios especificados por la variable de entorno. Si el archivo de destino está en uno de esos directorios, la ruta de acceso creada recientemente se copia en pathname. Si no se encuentra el filename archivo, pathname contiene una cadena vacía terminada en NULL.

El búfer de pathname debe tener _MAX_PATH caracteres como mínimo, para dar cabida a todo el nombre de ruta de acceso creada. Si no es así, _searchenv_s puede saturar el búfer de pathname y generar un comportamiento inesperado.

_wsearchenv_s es una versión con caracteres anchos de _searchenv_s; los argumentos a _wsearchenv_s son cadenas de caracteres anchos. Por lo demás,_wsearchenv_s y _searchenv_s se comportan de forma idéntica.

En C++, el uso de estas funciones se simplifica con las sobrecargas de plantilla; las sobrecargas pueden realizar una inferencia automáticamente de la longitud de búfer (lo que elimina el requisito de especificar un argumento de tamaño) y pueden reemplazar automáticamente funciones anteriores no seguras con sus homólogos seguros más recientes. Para obtener más información, consulte Sobrecargas de plantillas seguras.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Asignaciones de rutinas de texto genérico

Rutina Tchar.h	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Requisitos

Routine	Encabezado necesario
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> o <wchar.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

// 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

Consulte también

Control de directorio
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv