_searchenv_s, _wsearchenv_s

 

Para obtener la documentación más reciente de Visual Studio 2017 RC, consulte Documentación de Visual Studio 2017 RC.

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.

System_CAPS_ICON_important.jpg Importante

Esta API no se puede usar en aplicaciones que se ejecutan en Windows en tiempo de ejecución. Para 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 de la pathnamebúfer.

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

filenamevarnamepathnamenumberOfElementsValor devueltoContenido de pathname
anycualquieraNULLanyEINVALno disponible
NULLcualquieracualquieracualquieraEINVALno cambia
anycualquieraany<= 0EINVALno cambia

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

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 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, consulta Secure Template Overloads.

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
RutinaEncabezado necesario
_searchenv_s<stdlib.h>
_wsearchenv_s<stdlib.h> o <wchar.h>

Para obtener más información sobre compatibilidad, vea Compatibility.

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

No es aplicable. Para llamar a la función estándar de C, use PInvoke. Para obtener más información, vea Ejemplos de invocación de plataforma.

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

Mostrar: