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