_searchenv, _wsearchenv

Searches for a file using environment paths.

void _searchenv( const char *filename, const char *varname, char *pathname );

void _wsearchenv( const wchar_t *filename, const wchar_t *varname, wchar_t *pathname );

Routine Required Header Compatibility
_searchenv <stdlib.h> Win 95, Win NT
_wsearchenv <stdlib.h> or <wchar.h> Win NT

For additional compatibility information, see Compatibility in the Introduction.

Libraries

LIBC.LIB Single thread static library, retail version
LIBCMT.LIB Multithread static library, retail version
MSVCRT.LIB Import library for MSVCRT.DLL, retail version

Return Value

None

Parameters

filename

Name of file to search for

varname

Environment to search

pathname

Buffer to store complete path

Remarks

The _searchenv 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._searchenv is case sensitive, so varname should match the case of the environment variable.

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 must be large enough to accomodate the full length of the constructed path name. Otherwise, _searchenv will overwite the pathname buffer resulting in unexpected behavior. This condition can be avoided by ensuring that the length of the constructed path name does not exceed the size of the pathname buffer, by calculating the maximum sum of the filename and varname lengths before calling _searchenv.

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

Generic-Text Routine Mappings

TCHAR.H Routine _UNICODE & _MBCS Not Defined _MBCS Defined _UNICODE Defined
_tsearchenv _searchenv _searchenv _wsearchenv

Example

/* SEARCHEN.C: This program searches for a file in
 * a directory specified by an environment variable.
 */

#include <stdlib.h>
#include <stdio.h>

void main( void )
{
   char pathbuffer[_MAX_PATH];
   char searchfile[] = "CL.EXE";
   char envvar[] = "PATH";

   /* Search for file in PATH environment variable: */
   _searchenv( searchfile, envvar, pathbuffer );
   if( *pathbuffer != '\0' )
      printf( "Path for %s: %s\n", searchfile, pathbuffer );
   else
      printf( "%s not found\n", searchfile );
}

Output

Path for CL.EXE: C:\msvcnt\c32\bin\CL.EXE

Directory Control Routines

See Also   getenv, _putenv