Export (0) Print
Expand All
div
eof
Expand Minimize

_searchenv_s, _wsearchenv_s 

Searches for a file using environment paths. These are versions of _searchenv, _wsearchenv with security enhancements as described in Security Enhancements in the CRT.


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 pathname buffer.

Zero if successful; an error code on failure.

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

Error Conditions
filename varname pathname numberOfElements Return value Contents of pathname

any

any

NULL

any

EINVAL

n/a

NULL

any

any

any

EINVAL

not changed

any

any

any

<= 0

EINVAL

not changed

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.

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
Tchar.h routine _UNICODE and _MBCS not defined _MBCS defined _UNICODE defined

_tsearchenv_s

_searchenv_s

_searchenv_s

_wsearchenv_s

Routine Required header Compatibility

_searchenv_s

<stdlib.h>

Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003

_wsearchenv_s

<stdlib.h> or <wchar.h>

Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003

For more compatibility information, see Compatibility in the Introduction.

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

Sample Output

Path for CL.EXE:
C:\Program Files\Microsoft Visual Studio 2005\VC7\BIN\CL.EXE

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

Community Additions

ADD
Show:
© 2014 Microsoft