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

Filespec引数で指定されたファイルと一致するファイル名の最初のインスタンスに関する情報を指定します。Provide information about the first instance of a file name that matches the file specified in the filespec argument.

構文Syntax

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

fileinfofileinfo
ファイル情報バッファー。File information buffer.

戻り値Return Value

正常に実行された場合、 _findfirstは、 filespec仕様に一致するファイルまたはファイルのグループを識別する一意の検索ハンドルを返します。これは、以降の_findnextまた_findcloseはの呼び出しで使用できます。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. それ以外の場合、 _findfirstは-1 を返し、 errnoを次のいずれかの値に設定します。Otherwise, _findfirst returns -1 and sets errno to one of the following values.

errno の値errno value 条件Condition
EINVALEINVAL 無効なパラメーター: filespecまたはfileinfoNULLでした。Invalid parameter: filespec or fileinfo was NULL. または、オペレーティング システムが予期しないエラーを返しました。Or, the operating system returned an unexpected error.
ENOENTENOENT 一致しないファイルの指定。File specification that could not be matched.
ENOMEMENOMEM メモリ不足です。Insufficient memory.
EINVALEINVAL ファイル名の指定が無効であるか、指定されたファイル名がMAX_PATHを超えています。Invalid file name specification or the file name given was larger than MAX_PATH.

リターン コードの詳細については、「_doserrno、errno、_sys_errlist、および _sys_nerr」を参照してください。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

_Findfirstまたは_findnext関数 (または variant) のいずれかを使用して終了した後、 _findcloseを呼び出す必要があります。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.

Wプレフィックスを持つこれらの関数のバリエーションは、ワイド文字バージョンです。それ以外の場合は、対応する1バイト関数と同じです。The variations of these functions that have the w prefix are wide-character versions; otherwise, they are identical to the corresponding single-byte functions.

これらの関数のバリエーションは、32 ビットや 64 ビットの時刻型と、32 ビットや 64 ビットのファイル サイズをサポートします。Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file sizes. 最初の数値サフィックス (32または64) は、時刻型のサイズを示します。2番目のサフィックスは、 i32またはi64のいずれかで、ファイルサイズが32ビットまたは64ビットの整数として表されるかどうかを示します。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. 32 ビットと 64 ビットの時刻型とファイル サイズをサポートするバージョンについては、次の表を参照してください。For information about which versions support 32-bit and 64-bit time types and file sizes, see the following table. I32またはi64サフィックスは、time 型のサイズと同じ場合は省略されます。そのため _findfirst64 64 ビットのファイル長もサポートされ、 _findfirst32は32ビットのファイルの長さのみをサポートします。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.

これらの関数は、 fileinfoパラメーターに対してさまざまな形式の _finddata_t構造を使用します。These functions use various forms of the _finddata_t structure for the fileinfo parameter. 構造体の詳細については、「ファイル名検索関数」を参照してください。For more information about the structure, see Filename Search Functions.

64 ビットの時刻型を使用するバリエーションでは、3000 年 12 月 31 日 23:59:59 (UTC) までのファイルの作成日を表現できます。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. 32 ビットの時刻型を使用するバリエーションでは、2038 年 1 月 18 日 23:59:59 (UTC) までの日付のみを表現できます。Those that use 32-bit time types represent dates only through 23:59:59 January 18, 2038, UTC. これらの関数の日付範囲の下限は、いずれも 1970 年 1 月 1 日の午前 0 時です。Midnight, January 1, 1970, is the lower bound of the date range for all these functions.

時間のサイズを明示的に指定するバージョンを使用する具体的な理由がない限り、 _findfirstまたは _wfindfirstを使用するか、3 GB を超えるファイルサイズをサポートする必要がある場合は _findfirsti64または _wfindfirsti64を使用します。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. これらの関数はすべて 64 ビットの時刻型です。All these functions use the 64-bit time type. 以前のバージョンでは、これらの関数は 32 ビットの時刻型を使用していました。In earlier versions, these functions used a 32-bit time type. これがアプリケーションの互換性に影響する変更である場合は、 _USE_32BIT_TIME_Tを定義して、以前の動作に戻すことができます。If this is a breaking change for an application, you might define _USE_32BIT_TIME_T to revert to the old behavior. _USE_32BIT_TIME_Tが定義されている場合、 _findfirst_Finfirsti64、および対応する Unicode バージョンは32ビット時刻を使用します。If _USE_32BIT_TIME_T is defined, _findfirst, _finfirsti64, and their corresponding Unicode versions use a 32-bit time.

既定では、この関数のグローバル状態はアプリケーションにスコープが設定されています。By default, this function's global state is scoped to the application. これを変更するには、「 CRT でのグローバル状態」を参照してください。To change this, see Global state in the CRT.

_findfirst の時刻型とファイル長型のバリエーションTime Type and File Length Type Variations of _findfirst

関数Functions _USE_32BIT_TIME_T定義されていますか?_USE_32BIT_TIME_T defined? 時刻型Time type ファイル長型File length type
_findfirst_wfindfirst_findfirst, _wfindfirst 未定義Not defined 64 ビット64-bit 32 ビット32-bit
_findfirst_wfindfirst_findfirst, _wfindfirst 定義済みDefined 32 ビット32-bit 32 ビット32-bit
_findfirst32_wfindfirst32_findfirst32, _wfindfirst32 マクロ定義の影響を受けないNot affected by the macro definition 32 ビット32-bit 32 ビット32-bit
_findfirst64_wfindfirst64_findfirst64, _wfindfirst64 マクロ定義の影響を受けないNot affected by the macro definition 64 ビット64-bit 64 ビット64-bit
_findfirsti64_wfindfirsti64_findfirsti64, _wfindfirsti64 未定義Not defined 64 ビット64-bit 64 ビット64-bit
_findfirsti64_wfindfirsti64_findfirsti64, _wfindfirsti64 定義済みDefined 32 ビット32-bit 64 ビット64-bit
_findfirst32i64_wfindfirst32i64_findfirst32i64, _wfindfirst32i64 マクロ定義の影響を受けないNot affected by the macro definition 32 ビット32-bit 64 ビット64-bit
_findfirst64i32_wfindfirst64i32_findfirst64i32, _wfindfirst64i32 マクロ定義の影響を受けないNot affected by the macro definition 64 ビット64-bit 32 ビット32-bit

汎用テキスト ルーチンのマップGeneric-Text Routine Mappings

Tchar.h のルーチンTchar.h routine _UNICODE および _MBCS が未定義の場合_UNICODE and _MBCS not defined _MBCS が定義されている場合_MBCS defined _UNICODE が定義されている場合_UNICODE defined
_tfindfirst_tfindfirst _findfirst_findfirst _findfirst_findfirst _wfindfirst_wfindfirst
_tfindfirst32_tfindfirst32 _findfirst32_findfirst32 _findfirst32_findfirst32 _wfindfirst32_wfindfirst32
_tfindfirst64_tfindfirst64 _findfirst64_findfirst64 _findfirst64_findfirst64 _wfindfirst64_wfindfirst64
_tfindfirsti64_tfindfirsti64 _findfirsti64_findfirsti64 _findfirsti64_findfirsti64 _wfindfirsti64_wfindfirsti64
_tfindfirst32i64_tfindfirst32i64 _findfirst32i64_findfirst32i64 _findfirst32i64_findfirst32i64 _wfindfirst32i64_wfindfirst32i64
_tfindfirst64i32_tfindfirst64i32 _findfirst64i32_findfirst64i32 _findfirst64i32_findfirst64i32 _wfindfirst64i32_wfindfirst64i32

必要条件Requirements

関数Function 必須ヘッダーRequired header
_findfirst_findfirst <io.h><io.h>
_findfirst32_findfirst32 <io.h><io.h>
_findfirst64_findfirst64 <io.h><io.h>
_findfirsti64_findfirsti64 <io.h><io.h>
_findfirst32i64_findfirst32i64 <io.h><io.h>
_findfirst64i32_findfirst64i32 <io.h><io.h>
_wfindfirst_wfindfirst <io.h> または <wchar.h><io.h> or <wchar.h>
_wfindfirst32_wfindfirst32 <io.h> または <wchar.h><io.h> or <wchar.h>
_wfindfirst64_wfindfirst64 <io.h> または <wchar.h><io.h> or <wchar.h>
_wfindfirsti64_wfindfirsti64 <io.h> または <wchar.h><io.h> or <wchar.h>
_wfindfirst32i64_wfindfirst32i64 <io.h> または <wchar.h><io.h> or <wchar.h>
_wfindfirst64i32_wfindfirst64i32 <io.h> または <wchar.h><io.h> or <wchar.h>

互換性について詳しくは、「 Compatibility」をご覧ください。For more compatibility information, see Compatibility.

関連項目See also

システム コールSystem Calls
ファイル名検索関数Filename Search Functions