3 out of 11 rated this helpful - Rate this topic

_findfirst, _wfindfirst

Visual Studio 2005

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 wildcards).

fileinfo: File information buffer.

Return Value

If successful, _findfirst returns a unique search handle identifying the file or group of files matching 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: Not enough memory or the file name given was greater than MAX_PATH.

EINVAL: Invalid file name specification.

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.

Remarks

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

The variations of these functions with 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 numerical suffix (32 or 64) indicates the size of the time type used; the second suffix is either i32 or i64, indicating 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 _find, _wfind Functions.

The variations that use a 64-bit time type allow file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas those using 32-bit time types only represent dates through 19:14:07 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 greater than 3 GB, use _findfirsti64 or _wfindfirsti64. All these functions use the 64-bit time type in Visual C++ 2005. In previous 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 get 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 type	File length type
_findfirst, _wfindfirst	Not defined	64-bit	32-bit
_findfirst, _wfindfirst	Defined	32-bit	32-bit
_findfirst32, _wfindfirst32	Not affected by the macro definition	32-bit	32-bit
_findfirst64, _wfindfirst64	Not affected by the macro definition	64-bit	64-bit
_findfirsti64, _wfindfirsti64	Not defined	64-bit	64-bit
_findfirsti64, _wfindfirsti64	Defined	32-bit	64-bit
_findfirst32i64, _wfindfirst32i64	Not affected by the macro definition	32-bit	64-bit
_findfirst64i32, _wfindfirst64i32	Not affected by the macro definition	64-bit	32-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

Requirements

Function	Required header	Compatibility
_findfirst	<io.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
_findfirst32	<io.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
_findfirst64	<io.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
_findfirsti64	<io.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
_findfirst32i64	<io.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
_findfirst64i32	<io.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
_wfindfirst	<io.h> or <wchar.h>	Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
_wfindfirst32	<io.h> or <wchar.h>	Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
_wfindfirst64	<io.h> or <wchar.h>	Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
_wfindfirsti64	<io.h> or <wchar.h>	Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
_wfindfirst32i64	<io.h> or <wchar.h>	Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003
_wfindfirst64i32	<io.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.

.NET Framework Equivalent

System::IO::DirectoryInfo::GetFiles

Reference

System Calls
_find, _wfind Functions

Did you find this helpful? Yes No

Not accurate

Not enough depth

Need more code examples

(1500 characters remaining)

Community Additions

ADD