_searchenv_s, _wsearchenv_s

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at _searchenv_s, _wsearchenv_s.

Searches for a file by using environment paths. These versions of _searchenv, _wsearchenv have security enhancements, as described in Security Features in the CRT.

Syntax

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  

Parameters

[in] filename
Name of the file to search for.

[in] varname
Environment to search.

[out] pathname
Buffer to store the complete path.

[in] numberOfElements
Size of the pathnamebuffer.

Return Value

Zero if successful; an error code on failure.

If filename is an empty string, the return value is ENOENT.

Error Conditions

If any of these error conditions occurs, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, these functions set errno to EINVAL and return EINVAL.

Remarks

The _searchenv_s routine searches for the target file in the specified domain. The varname variable can be any environment or user-defined variable that specifies a list of directory paths, such as PATH, LIB, and INCLUDE. Because _searchenv_s is case-sensitive, varname should match the case of the environment variable. If varname does not match the name of an environment variable defined in the process's environment, the function returns zero and the pathname variable is unchanged.

The routine searches first for the file in the current working directory. If it does not find the file, it looks next through the directories specified by the environment variable. If the target file is in one of those directories, the newly created path is copied into pathname. If the filename file is not found, pathname contains an empty null-terminated string.

The pathname buffer should be at least _MAX_PATH characters long to accommodate the full length of the constructed path name. Otherwise, _searchenv_s might overrun the pathname buffer resulting in unexpected behavior.

_wsearchenv_s is a wide-character version of _searchenv_s; the arguments to _wsearchenv_s are wide-character strings. _wsearchenv_s and _searchenv_s behave identically otherwise.

In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see Secure Template Overloads.

Generic-Text Routine Mappings

Requirements

For more compatibility information, see Compatibility.

Example

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

.NET Framework Equivalent

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

See Also

Directory Control
_searchenv, _wsearchenv
getenv, _wgetenv
_putenv, _wputenv