ファイル名検索関数

これらの関数は指定されたファイル名を検索し、検索を閉じます:

• _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 は、前回の filespec への呼び出しで指定された _findfirst引数に一致する次の名前を検索します。 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データ型のフィールドと同じですが、nameフィールド_wfinddata_tchar型ではなくwchar_t型である点が異なります。 それ以外の場合、 _wfindfirst と _wfindnext は、 _findfirst と _findnextと同じように動作します。

_findfirst と _findnext は 64 ビット時刻型を使用します。 従来の 32 ビット時刻型を使用する場合は、 _USE_32BIT_TIME_Tを定義できます。 32 サフィックスが名前に含まれるこれらの関数のバージョンでは 32 ビットの時刻型が使用され、64 サフィックスを持つ関数は 64 ビットの時刻型を使用します。

関数 _findfirst32i64、 _findnext32i64、 _wfindfirst32i64、 _wfindnext32i64 も 32 ビットの時刻の種類のバージョンの関数と同様に動作しますが、64 ビット ファイルの長さを使用して返す点が異なります。 関数 _findfirst64i32、 _findnext64i32、 _wfindfirst64i32、 _wfindnext64i32 は 64 ビットの時刻型ですが 32 ビット ファイルの長さを使用します。 これらの関数は、時間とファイル サイズの異なる型を持つフィールドの _finddata_t 型の適切なバリエーションを使用します。

_finddata_t は実際には _finddata64i32_t ( _finddata32_t が定義されている場合は _USE_32BIT_TIME_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

_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

関連項目

システム呼び出し