_find、_wfind 系関数

更新 : 2007 年 11 月

これらの関数は、指定されたファイル名を検索したり、検索を終了したりします。

• _findnext、_wfindnext

• _findfirst、_wfindfirst

• _findclose

解説

_findfirst 関数は、引数 filespec で指定したファイルに一致する最初のファイル名の情報を返します。filespec には、ホストのオペレーティング システムでサポートされているワイルドカードの組み合わせをすべて使用できます

関数は、IO.h で定義されている _finddata_t 構造体にファイルの情報を返します。このファミリの各種の関数が使用する _finddata_t 構造体には多くの種類があります。基本の _finddata_t 構造体は次の要素で構成されます。

• unsigned attrib
  ファイル属性。

• time_t time_create
  ファイル作成時刻 (FAT ファイル システムの場合は –1L)。この時刻は UTC 形式で格納されます。現地時刻に変換するには、localtime_s を使用します。

• time_t time_access
  最新ファイル アクセス時刻 (FAT ファイル システムの場合は –1L)。この時刻は UTC 形式で格納されます。現地時刻に変換するには、localtime_s を使用します。

• time_t time_write
  最新ファイル書き込み時刻この時刻は UTC 形式で格納されます。現地時刻に変換するには、localtime_s を使用します。

• _fsize_t size
  ファイルの長さ (バイト数)

• char name[ _MAX_PATH]
  一致したファイルまたはディレクトリの名前を表す NULL 終端文字列。パス名は付きません。

ファイル作成時刻および最新ファイル アクセス時刻をサポートしていない FAT システムなどのファイル システムでは、time_create と time_access フィールドは常に –1L です。

_MAX_PATH は、Stdlib.h で 260 バイトに定義されています。

検索時の制約条件として、_A_RDONLY などのターゲットの属性は指定できません。これらの属性は、_finddata_t 構造体の attrib フィールドで返されます。IO.h で定義されている次の値が設定されます。ただし、これら以外の値が attrib フィールドに設定される可能性もあるので注意してください。

• _A_ARCH
  アーカイブ。ファイルが変更されるたびに設定され、BACKUP コマンドによって消去されます。値は 0x20 です。

• _A_HIDDEN
  隠しファイル。/AH オプションを使用しない場合、通常は DIR コマンドで表示されません。通常のファイルに関する情報とこの属性を持つファイルを返します。値は 0x02 です。

• _A_NORMAL
  通常。ファイルには他の属性が設定されておらず、制限なくファイルを読み書きできます。値は 0x00 です。

• _A_RDONLY
  読み取り専用。ファイルを書き込み用として開いたり、同じ名前のファイルを作成したりすることはできません。値は 0x01 です。

• _A_SUBDIR
  サブディレクトリ。値は 0x10 です。

• _A_SYSTEM
  システム ファイル。/A または /A:S オプションを使用しない場合、通常は DIR コマンドで表示されません。値は 0x04 です。

_findnext は、前の _findfirst の呼び出しで指定した引数 filespec と一致する次の名前を検索します。引数 fileinfo は、前の _findfirst の呼び出しで初期化された構造体を指す必要があります。一致が見つかった場合、fileinfo 構造体の内容は前のように変更されます。それ以外の場合は変更されません。_findclose は指定された検索ハンドルを閉じ、_findfirst と _findnext に関連するすべてのリソースを解放します。_findfirst または _findnext が返すハンドルを _findclose に渡すと、関数に渡したパスのディレクトリに対して削除などの変更操作ができるようになります。

_find 関数を入れ子にすることができます。たとえば、_findfirst または _findnext を呼び出して見つかったファイルがサブディレクトリの場合は、_findfirst または _findnext を呼び出して新たな検索を開始できます。

_wfindfirst 関数と _wfindnext 関数は、_findfirst 関数と _findnext 関数のワイド文字バージョンです。ワイド文字バージョンの構造体引数は、IO.h および Wchar.h で定義されている _wfinddata_t データ型です。このデータ型のフィールドは _finddata_t データ型とほとんど同じですが、_wfinddata_t では name フィールドが char 型でなく wchar_t 型になります。それ以外の点では、_wfindfirst と _wfindnext の動作は、_findfirst と _findnext と同じです。

Visual C++ 2005 では、_findfirst と _findnext は 64 ビットの時刻型を使用します。以前の 32 ビットの時刻型を使用する場合は、_USE_32BIT_TIME_T を定義します。名前に 32 のサフィックスが付いているバージョンは 32 ビットの時刻型を使用し、64 のサフィックスが付いているバージョンは 64 ビットの時刻型を使用します。

_findfirst32i64、_findnext32i64、_wfindfirst32i64、および _wfindnext32i64 関数の動作も、64 ビットのファイルの長さを返すことを除いて対応する 32 ビットの時刻型のバージョンと同じです。_findfirst64i32、_findnext64i32、_wfindfirst64i32、および _wfindnext64i32 関数は 64 ビットの時刻型を使用しますが、32 ビットのファイルの長さを使用します。これらの関数は、時刻とファイル サイズのフィールドの型が異なる _finddata_t 型の適切なバージョンを使用します。

_finddata_t は、実際には _finddata64i32_t になるマクロです (_USE_32BIT_TIME_T が定義されている場合は _finddata32_t)。次の表に、各種の _finddata_t をまとめます。

構造体	時刻型	ファイル サイズ型
_finddata_t, _wfinddata_t	__time64_t	_fsize_t
_finddata32_t, _wfinddata32_t	__time32_t	_fsize_t
__finddata64_t, __wfinddata64_t	__time64_t	__int64
_finddata32i64_t, _wfinddata32i64_t	__time32_t	__int64
_finddata64i32_t, _wfinddata64i32_t	__time64_t	_fsize_t

Visual C++ 2005 では、_fsize_t は unsigned long (32 ビット) の typedef です。

使用例

// crt_find.c
// This program uses the 32-bit _find functions to print
// a list of all files (and their attributes) with a .C extension
// in the current directory.

#include <stdio.h>
#include <stdlib.h>
#include <io.h>
#include <time.h>

int main( void )
{
   struct _finddata_t c_file;
   intptr_t hFile;

   // Find first .c file in current directory 
   if( (hFile = _findfirst( "*.c", &c_file )) == -1L )
      printf( "No *.c files in current directory!\n" );
   else
   {
      printf( "Listing of .c files\n\n" );
      printf( "RDO HID SYS ARC  FILE         DATE %25c SIZE\n", ' ' );
      printf( "--- --- --- ---  ----         ---- %25c ----\n", ' ' );
      do {
         char buffer[30];
         printf( ( c_file.attrib & _A_RDONLY ) ? " Y  " : " N  " );
         printf( ( c_file.attrib & _A_HIDDEN ) ? " Y  " : " N  " );
         printf( ( c_file.attrib & _A_SYSTEM ) ? " Y  " : " N  " );
         printf( ( c_file.attrib & _A_ARCH )   ? " Y  " : " N  " );
         ctime_s( buffer, _countof(buffer), &c_file.time_write );
         printf( " %-12s %.24s  %9ld\n",
            c_file.name, buffer, c_file.size );
      } while( _findnext( hFile, &c_file ) == 0 );
      _findclose( hFile );
   }
}

Listing of .c files

RDO HID SYS ARC  FILE         DATE                           SIZE
--- --- --- ---  ----         ----                           ----
 N   N   N   Y   blah.c       Wed Feb 13 09:21:42 2002       1715
 N   N   N   Y   test.c       Wed Feb 06 14:30:44 2002        312

参照

参照

システム コール