_searchenv_s, _wsearchenv_s

Artículo
06/09/2015

Busca un archivo mediante rutas de acceso del entorno. Estas versiones de _searchenv, _wsearchenv tienen mejoras de 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 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

Parámetros

[in] filename
Nombre del archivo que se va a buscar.
[in] varname
Entorno en el que se va a buscar.
[out] pathname
Búfer en el que se va a almacenar la ruta de acceso completa.
[in] numberOfElements
Tamaño del búfer pathname.

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
any	any	NULL	any	EINVAL	no disponible
NULL	any	any	any	EINVAL	no cambia
any	any	any	<= 0	EINVAL	no cambia

Si se produce una de estas condiciones de error, se invoca el 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 variable pathname no cambia.

La rutina busca el archivo primero en el directorio de trabajo actual. Si no encuentra el archivo, busca en 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 el archivo filename no se encuentra, pathname contiene una cadena vacía terminada en un valor nulo.

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 la necesidad 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, vea Sobrecargas de plantilla seguras.

Asignaciones de rutina 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

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

Para obtener más información sobre compatibilidad, vea 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 );
}