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

filespec 引数で指定されたファイルと一致するファイル名の最初のインスタンスに関する情報を提供します。

構文

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

パラメーター

filespec
ターゲット ファイルの指定 (ワイルドカード文字を含めることができます)。

fileinfo
ファイル情報バッファー。 fileinfo構造体の詳細については、「Filename 検索機能の解説」を参照Data 型マッピングを参照してください。 構造体は、パラメーターとして使用する関数と同じヘッダー ファイルで定義されます。

戻り値

成功した場合、_findfirst では、filespec の指定に一致するファイルまたはファイルのグループを識別する一意の検索ハンドルを返します。このハンドルは、_findnext または_findclose の以降の呼び出しに使用できます。 それ以外の場合、_findfirst では -1 を返し、errno を次の値のいずれかに設定します。

errno の値	条件
EINVAL	無効なパラメーター: filespec または fileinfo は NULL でした。 または、オペレーティング システムが予期しないエラーを返しました。
ENOENT	一致できなかったファイル指定。
ENOMEM	不十分なメモリ。
EINVAL	無効なファイル名の指定か、指定したファイル名が MAX_PATH を超えています。

これらのリターン コードとその他のリターン コードについては、「errno、_doserrno、_sys_errlist、_sys_nerr」を参照してください。

無効なパラメーターが渡された場合、これらの関数は、 Parameter 検証で説明されているように、無効なパラメーター ハンドラーを呼び出します。

解説

_findfirstまたは_findnext関数 (または任意のバリアント) の呼び出しが成功した後、_findcloseを呼び出_findfirst必要があります。 _findclose は、アプリケーションでこれらの関数によって使用されるリソースを解放します。 無効なハンドルに対して _findclose を呼び出すと、 -1 が返され、 errno が EINVALに設定されます。

w プレフィックスを持つこれらの関数のバリエーションはワイド文字バージョンです。それ以外の場合は、対応する 1 バイト関数と同じです。

これらの関数のバリエーションは、32 ビットや 64 ビットの時刻型と、32 ビットや 64 ビットのファイル サイズをサポートします。 最初の数字のサフィックス (32 または 64) は、時刻型のサイズを示します。2 番目のサフィックスは i32 または i64で、ファイル サイズが 32 ビットの整数として表されるか、それとも 64 ビットの整数として表されるかを示します。 32 ビットと 64 ビットの時刻型とファイル サイズをサポートするバージョンについては、次の表を参照してください。 i32またはi64サフィックスは時間型のサイズと同じ場合は省略されるため、_findfirst64は 64 ビットのファイル長もサポートし、_findfirst32は 32 ビットのファイル長のみをサポートします。

これらの関数は、fileinfo パラメーターの多様な形式の _finddata_t 構造体を使用します。 構造体の詳細については、「 Filename 検索機能を参照してください。

64 ビットの時刻型を使用するバリエーションでは、3000 年 12 月 31 日 23:59:59 (UTC) までのファイルの作成日を表現できます。 32 ビット時刻型を使用するものは、UTC の 2038 年 1 月 18 日 23:59:59 までの日付のみを表します。 これらの関数の日付範囲の下限は、いずれも 1970 年 1 月 1 日の午前 0 時です。

時間のサイズを明示的に指定するバージョンを使う理由が特にない場合は、_findfirst または _wfindfirst を使用します。また、3 GB を超えるファイル サイズをサポートする必要がある場合は、_findfirsti64 または _wfindfirsti64 を使用します。 これらの関数はすべて 64 ビットの時刻型です。 以前のバージョンでは、これらの関数は 32 ビットの時刻型を使用していました。 この変更がアプリケーションの破壊的変更である場合は、古い動作に戻す _USE_32BIT_TIME_T を定義できます。 _USE_32BIT_TIME_T を定義する場合、_findfirst、_findfirsti64、およびそれに対応する Unicode バージョンは 32 ビット時刻を使用します。

既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 この動作を変更するには、「CRT でのグローバル状態」を参照してください。

_findfirst の時刻型とファイル長型のバリエーション

関数	_USE_32BIT_TIME_T は定義済み?	時刻型	ファイル長型
_findfirst, _wfindfirst	未定義	64 ビット	32 ビット
_findfirst, _wfindfirst	定義済み	32 ビット	32 ビット
_findfirst32, _wfindfirst32	マクロ定義の影響を受けない	32 ビット	32 ビット
_findfirst64, _wfindfirst64	マクロ定義の影響を受けない	64 ビット	64 ビット
_findfirsti64, _wfindfirsti64	未定義	64 ビット	64 ビット
_findfirsti64, _wfindfirsti64	定義済み	32 ビット	64 ビット
_findfirst32i64, _wfindfirst32i64	マクロ定義の影響を受けない	32 ビット	64 ビット
_findfirst64i32, _wfindfirst64i32	マクロ定義の影響を受けない	64 ビット	32 ビット

汎用テキスト ルーチンのマップ

Tchar.h ルーチン	_UNICODE と _MBCS が定義されていない	_MBCS が定義されている	_UNICODE が定義されている
_tfindfirst	_findfirst	_findfirst	_wfindfirst
_tfindfirst32	_findfirst32	_findfirst32	_wfindfirst32
_tfindfirst64	_findfirst64	_findfirst64	_wfindfirst64
_tfindfirsti64	_findfirsti64	_findfirsti64	_wfindfirsti64
_tfindfirst32i64	_findfirst32i64	_findfirst32i64	_wfindfirst32i64
_tfindfirst64i32	_findfirst64i32	_findfirst64i32	_wfindfirst64i32

要件

機能	必須ヘッダー
_findfirst	<io.h>
_findfirst32	<io.h>
_findfirst64	<io.h>
_findfirsti64	<io.h>
_findfirst32i64	<io.h>
_findfirst64i32	<io.h>
_wfindfirst	<io.h> または <wchar.h>
_wfindfirst32	<io.h> または <wchar.h>
_wfindfirst64	<io.h> または <wchar.h>
_wfindfirsti64	<io.h> または <wchar.h>
_wfindfirst32i64	<io.h> または <wchar.h>
_wfindfirst64i32	<io.h> または <wchar.h>

互換性の詳細については、「 Compatibility」を参照してください。

関連項目

システム呼び出し
ファイル名検索機能