_findfirst、_wfindfirst

更新 : 2007 年 11 月

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
  ファイル情報バッファ。

戻り値

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

• EINVAL
  無効なパラメータ。filespec または fileinfo が NULL です。または、オペレーティング システムが予期しないエラーを返しました。

• ENOENT
  一致するファイルのないファイル指定

• ENOMEM
  メモリ不足。

• EINVAL
  無効なファイル名の指定、または指定されたファイル名が MAX_PATH を超えています。

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

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

解説

_findfirst 関数または _findnext 関数 (またはそのバリアント) を使用した後で、_findclose を呼び出す必要があります。これによって、アプリケーションでこれらの関数が使用していたリソースが解放されます。

w プレフィックスが付いている関数はワイド文字のバージョンで、それ以外の点では対応する 1 バイト文字用の関数と同じです。

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

これらの関数は、fileinfo パラメータに _finddata_t 構造体の各種の形式を使用します。この構造体の詳細については、「_find、_wfind 系関数」を参照してください。

64 ビットの時刻型を使用するバージョンでは、ファイルの作成日を世界協定時刻 (UTC) 3000 年 12 月 31 日 23 時 59 分 59 秒まで表現できます。32 ビットの時刻型を使用するバージョンでは、ファイルの作成日を 2038 年 1 月 18 日 19 時 14 分 07 秒までしか表現できません。これらの関数の日付範囲の下限は、すべて 1970 年 1 月 1 日の午前零時です。

時刻のサイズを明示的に指定するバージョンを使用する特別の理由がない限り、_findfirst または _wfindfirst を使用してください。3 GB を超えるサイズのファイルをサポートする必要がある場合は、_findfirsti64 または _wfindfirsti64 使用してください。Visual C++ 2005 では、すべての関数が 64 ビットの時刻型を使用します。以前のバージョンの関数は 32 ビットの時刻型を使用します。この変更点がアプリケーションの互換性に影響する場合は、_USE_32BIT_TIME_T を定義して以前の動作に戻します。_USE_32BIT_TIME_T を定義すると、_findfirst、_finfirsti64、および対応する Unicode バージョンは 32 ビットの時刻を使用します。

_findfirst の時刻型とファイル長の種類

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

必要条件

互換性の詳細については、「C ランタイム ライブラリ」の「互換性」を参照してください。

.NET Framework の相当するアイテム

System::IO::DirectoryInfo::GetFiles

参照

参照

システム コール

_find、_wfind 系関数