_findfirst, _findfirst32, _findfirst32i64, _findfirst64, _findfirst64i32, _findfirsti64, _wfindfirst, _wfindfirst32, _wfindfirst32i64, _wfindfirst64, _wfindfirst64i32, _wfindfirsti64

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

Provide information about the first instance of a file name that matches the file specified in the filespec argument.

intptr_t _findfirst(  
   const char *filespec,  
   struct _finddata_t *fileinfo   
);  
intptr_t _findfirst32(  
   const char *filespec,  
   struct _finddata32_t *fileinfo   
);  
intptr_t _findfirst64(  
   const char *filespec,  
   struct _finddata64_t *fileinfo   
);  
intptr_t _findfirsti64(  
   const char *filespec,  
   struct _finddatai64_t *fileinfo   
);  
intptr_t _findfirst32i64(  
   const char *filespec,  
   struct _finddata32i64_t *fileinfo   
);  
intptr_t _findfirst64i32(  
   const char *filespec,  
   struct _finddata64i32_t *fileinfo   
);  
intptr_t _wfindfirst(  
   const wchar_t *filespec,  
   struct _wfinddata_t *fileinfo   
);  
intptr_t _wfindfirst32(  
   const wchar_t *filespec,  
   struct _wfinddata32_t *fileinfo   
);  
intptr_t _wfindfirst64(  
   const wchar_t *filespec,  
   struct _wfinddata64_t *fileinfo   
);  
intptr_t _wfindfirsti64(  
   const wchar_t *filespec,  
   struct _wfinddatai64_t *fileinfo   
);  
intptr_t _wfindfirst32i64(  
   const wchar_t *filespec,  
   struct _wfinddata32i64_t *fileinfo   
);  
intptr_t _wfindfirst64i32(  
   const wchar_t *filespec,  
   struct _wfinddata64i32_t *fileinfo   
);  

Parameters

filespec
Target file specification (can include wildcard characters).

fileinfo
File information buffer.

If successful, _findfirst returns a unique search handle identifying the file or group of files that match the filespec specification, which can be used in a subsequent call to _findnext or to _findclose. Otherwise, _findfirst returns –1 and sets errno to one of the following values.

EINVAL
Invalid parameter: filespec or fileinfo was NULL. Or, the operating system returned an unexpected error.

ENOENT
File specification that could not be matched.

ENOMEM
Insufficient memory.

EINVAL
Invalid file name specification or the file name given was larger than MAX_PATH.

For more information about these and other return codes, see _doserrno, errno, _sys_errlist, and _sys_nerr.

If an invalid parameter is passed in, these functions invoke the invalid parameter handler, as described in Parameter Validation.

You must call _findclose after you are finished with either the _findfirst or _findnext function (or any variants). This frees resources used by these functions in your application.

The variations of these functions that have the w prefix are wide-character versions; otherwise, they are identical to the corresponding single-byte functions.

Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file sizes. The first numeric suffix (32 or 64) indicates the size of the time type; the second suffix is either i32 or i64, and indicates whether the file size is represented as a 32-bit or 64-bit integer. For information about which versions support 32-bit and 64-bit time types and file sizes, see the following table. The i32 or i64 suffix is omitted if it is the same as the size of the time type, so _findfirst64 also supports 64-bit file lengths and _findfirst32 supports only 32-bit file lengths.

These functions use various forms of the _finddata_t structure for the fileinfo parameter. For more information about the structure, see Filename Search Functions.

The variations that use a 64-bit time type enable file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC. Those that use 32-bit time types represent dates only through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions.

Unless you have a specific reason to use the versions that specify the time size explicitly, use _findfirst or _wfindfirst or, if you need to support file sizes larger than 3 GB, use _findfirsti64 or _wfindfirsti64. All these functions use the 64-bit time type. In earlier versions, these functions used a 32-bit time type. If this is a breaking change for an application, you might define _USE_32BIT_TIME_T to revert to the old behavior. If _USE_32BIT_TIME_T is defined, _findfirst, _finfirsti64, and their corresponding Unicode versions use a 32-bit time.

Time Type and File Length Type Variations of _findfirst

Functions_USE_32BIT_TIME_T defined?Time typeFile length type
_findfirst, _wfindfirstNot defined64-bit32-bit
_findfirst, _wfindfirstDefined32-bit32-bit
_findfirst32, _wfindfirst32Not affected by the macro definition32-bit32-bit
_findfirst64, _wfindfirst64Not affected by the macro definition64-bit64-bit
_findfirsti64, _wfindfirsti64Not defined64-bit64-bit
_findfirsti64, _wfindfirsti64Defined32-bit64-bit
_findfirst32i64, _wfindfirst32i64Not affected by the macro definition32-bit64-bit
_findfirst64i32, _wfindfirst64i32Not affected by the macro definition64-bit32-bit

Generic-Text Routine Mappings

Tchar.h routine_UNICODE and _MBCS not defined_MBCS defined_UNICODE defined
_tfindfirst_findfirst_findfirst_wfindfirst
_tfindfirst32_findfirst32_findfirst32_wfindfirst32
_tfindfirst64_findfirst64_findfirst64_wfindfirst64
_tfindfirsti64_findfirsti64_findfirsti64_wfindfirsti64
_tfindfirst32i64_findfirst32i64_findfirst32i64_wfindfirst32i64
_tfindfirst64i32_findfirst64i32_findfirst64i32_wfindfirst64i32
FunctionRequired header
_findfirst<io.h>
_findfirst32<io.h>
_findfirst64<io.h>
_findfirsti64<io.h>
_findfirst32i64<io.h>
_findfirst64i32<io.h>
_wfindfirst<io.h> or <wchar.h>
_wfindfirst32<io.h> or <wchar.h>
_wfindfirst64<io.h> or <wchar.h>
_wfindfirsti64<io.h> or <wchar.h>
_wfindfirst32i64<io.h> or <wchar.h>
_wfindfirst64i32<io.h> or <wchar.h>

For more compatibility information, see Compatibility in the Introduction.

System::IO::DirectoryInfo::GetFiles

System Calls
Filename Search Functions

Show: