_searchenv_s, _wsearchenv_s

Article
11/16/2012

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 pathnamebuffer.

Return Value

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.

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

Tchar.h routine	_UNICODE and _MBCS not defined	_MBCS defined	_UNICODE defined
_tsearchenv_s	_searchenv_s	_searchenv_s	_wsearchenv_s

Requirements

Routine	Required header
_searchenv_s	<stdlib.h>
_wsearchenv_s	<stdlib.h> or <wchar.h>

For more compatibility information, see Compatibility in the Introduction.

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 2005\VC7\BIN\CL.EXE

.NET Framework Equivalent

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

Share via