Win32 API 日本語リファレンス
ホームStorage.FileSystem › FindFirstFileW

FindFirstFileW

関数
条件に一致する最初のファイルを検索する。
DLLKERNEL32.dll文字セットUnicode (-W)呼出規約winapiSetLastErrorあり対応OSWindows XP 以降

シグネチャ

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

HANDLE FindFirstFileW(
    LPCWSTR lpFileName,
    WIN32_FIND_DATAW* lpFindFileData
);

パラメーター

名前方向説明
lpFileNameLPCWSTRin

ディレクトリまたはパス、およびファイル名。ファイル名にはワイルドカード文字(例: アスタリスク (*) や疑問符 (?))を含めることができます。

このパラメーターを NULL、無効な文字列(例: 空文字列 や終端の null 文字が欠落している文字列)、または末尾が円記号 (\) で終わる文字列にしてはいけません。

文字列がワイルドカード、ピリオド (.)、またはディレクトリ名で終わる場合、ユーザーはパス上のルートおよびすべてのサブディレクトリに対するアクセス権を持っている必要があります。

既定では、名前は MAX_PATH 文字に制限されます。この制限を 32,767 ワイド文字まで拡張するには、パスの先頭に "\\?\" を付加します。詳細については、ファイル、パス、および名前空間の名前付けを参照してください。

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を先頭に付加しなくても MAX_PATH 制限を解除するようにオプトインできます。詳細については、ファイル、パス、および名前空間の名前付けの「Maximum Path Length Limitation」セクションを参照してください。

lpFindFileDataWIN32_FIND_DATAW*out見つかったファイルまたはディレクトリに関する情報を受け取る WIN32_FIND_DATA 構造体へのポインター。

戻り値の型: HANDLE

公式ドキュメント

指定した名前(ワイルドカードを使用した場合は部分的な名前)に一致するファイルまたはサブディレクトリをディレクトリ内で検索します。(Unicode)

戻り値

関数が成功した場合、戻り値は後続の FindNextFile または FindClose の呼び出しで使用される検索ハンドルであり、 lpFindFileData パラメーターには最初に見つかったファイルまたはディレクトリに関する情報が格納されます。

関数が失敗した場合、または lpFileName パラメーターの検索文字列からファイルを見つけられなかった場合、戻り値は INVALID_HANDLE_VALUE となり、lpFindFileData の内容は不定です。拡張エラー情報を取得するには、 GetLastError 関数を呼び出します。

一致するファイルが見つからなかったために関数が失敗した場合、 GetLastError 関数は ERROR_FILE_NOT_FOUND を返します。

解説(Remarks)

FindFirstFile 関数は検索ハンドルを開き、指定したパターンに一致する名前を持つファイルのうち、ファイルシステムが最初に見つけたファイルに関する情報を返します。これは、同じファイル名文字列パターンを指定したときに、ディレクトリ一覧アプリケーション(dir コマンドなど)で最初に表示されるファイルまたはディレクトリと一致するとは限りません。これは、FindFirstFile が検索結果の並べ替えを行わないためです。詳細については、FindNextFile を参照してください。

以下のリストは、その他の検索の特性を示しています。

注意 まれなケース、または負荷の高いシステムでは、この関数が呼び出された時点で NTFS ファイルシステムのファイル属性情報が最新でない場合があります。最新の NTFS ファイルシステムのファイル属性を確実に取得するには、 GetFileInformationByHandle 関数を呼び出します。
検索ハンドルを確立した後は、それを使用して FindNextFile 関数により同じパターンに一致する他のファイルを検索できます。

検索ハンドルが不要になったら、CloseHandle ではなく FindClose 関数を使用して閉じます。

前述のとおり、FindFirstFilelpFileName 入力文字列では末尾の円記号 (\) を使用できないため、ルートディレクトリを検索する方法は分かりにくいかもしれません。ルートディレクトリのファイルを参照したり属性を取得したりする場合は、次のオプションが適用されます。

注意 文字列 "\\?\" を先頭に付加しても、ルートディレクトリへのアクセスは許可されません。

ネットワーク共有では、次の形式の lpFileName を使用できます: "\\Server\Share\*"。ただし、共有自体を指す lpFileName は使用できません。たとえば、"\\Server\Share" は無効です。

ルートディレクトリ以外のディレクトリを調べるには、末尾の円記号を付けずにそのディレクトリへのパスを使用します。たとえば、引数 "C:\Windows" は、"C:\Windows" 内のディレクトリやファイルについてではなく、ディレクトリ "C:\Windows" 自体に関する情報を返します。"C:\Windows" 内のファイルおよびディレクトリを調べるには、lpFileName として "C:\Windows\*" を使用します。

結果を照会してからその情報に基づいて操作するまでの間に、他のスレッドやプロセスが同じ名前のファイルを作成または削除する可能性があることに注意してください。これがアプリケーションにとって潜在的な懸念事項である場合、考えられる解決策の 1 つは、CreateFile 関数を CREATE_NEW(ファイルが存在する場合は失敗します)または OPEN_EXISTING(ファイルが存在しない場合は失敗します)とともに使用することです。

ディレクトリ内のすべてのファイルを一覧表示する 32 ビットアプリケーションを作成しており、そのアプリケーションが 64 ビットコンピューター上で実行される可能性がある場合は、FindFirstFile を呼び出す前に Wow64DisableWow64FsRedirection 関数を呼び出し、FindNextFile の最後の呼び出しの後に Wow64RevertWow64FsRedirection を呼び出す必要があります。詳細については、 File System Redirector を参照してください。

パスがシンボリックリンクを指している場合、 WIN32_FIND_DATA バッファーには、ターゲットではなくシンボリックリンクに関する情報が格納されます。

Windows 8 および Windows Server 2012 では、この関数は次のテクノロジによってサポートされています。

テクノロジ サポート
Server Message Block (SMB) 3.0 プロトコル はい
SMB 3.0 透過的フェールオーバー (TFO) はい
SMB 3.0 スケールアウトファイル共有 (SO) はい
クラスターの共有ボリュームファイルシステム (CsvFS) はい
回復性ファイルシステム (ReFS) はい

次の C++ の例は、FindFirstFile の最小限の使用方法を示しています。

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

void _tmain(int argc, TCHAR *argv[])
{
   WIN32_FIND_DATA FindFileData;
   HANDLE hFind;

   if( argc != 2 )
   {
      _tprintf(TEXT("Usage: %s [target_file]\n"), argv[0]);
      return;
   }

   _tprintf (TEXT("Target file is %s\n"), argv[1]);
   hFind = FindFirstFile(argv[1], &FindFileData);
   if (hFind == INVALID_HANDLE_VALUE) 
   {
      printf ("FindFirstFile failed (%d)\n", GetLastError());
      return;
   } 
   else 
   {
      _tprintf (TEXT("The first file found is %s\n"), 
                FindFileData.cFileName);
      FindClose(hFind);
   }
}

別の例については、 Listing the Files in a Directory を参照してください。

メモ

fileapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして FindFirstFile を定義します。エンコード中立のエイリアスの使用を、エンコード中立でないコードと混在させると、コンパイルエラーまたは実行時エラーを引き起こす不一致につながる可能性があります。詳細については、関数プロトタイプの規則を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// KERNEL32.dll  (Unicode / -W)
#include <windows.h>

HANDLE FindFirstFileW(
    LPCWSTR lpFileName,
    WIN32_FIND_DATAW* lpFindFileData
);
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true, ExactSpelling = true)]
static extern IntPtr FindFirstFileW(
    [MarshalAs(UnmanagedType.LPWStr)] string lpFileName,   // LPCWSTR
    IntPtr lpFindFileData   // WIN32_FIND_DATAW* out
);
<DllImport("KERNEL32.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function FindFirstFileW(
    <MarshalAs(UnmanagedType.LPWStr)> lpFileName As String,   ' LPCWSTR
    lpFindFileData As IntPtr   ' WIN32_FIND_DATAW* out
) As IntPtr
End Function
' lpFileName : LPCWSTR
' lpFindFileData : WIN32_FIND_DATAW* out
Declare PtrSafe Function FindFirstFileW Lib "kernel32" ( _
    ByVal lpFileName As LongPtr, _
    ByVal lpFindFileData As LongPtr) As LongPtr
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

FindFirstFileW = ctypes.windll.kernel32.FindFirstFileW
FindFirstFileW.restype = ctypes.c_void_p
FindFirstFileW.argtypes = [
    wintypes.LPCWSTR,  # lpFileName : LPCWSTR
    ctypes.c_void_p,  # lpFindFileData : WIN32_FIND_DATAW* out
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('KERNEL32.dll')
FindFirstFileW = Fiddle::Function.new(
  lib['FindFirstFileW'],
  [
    Fiddle::TYPE_VOIDP,  # lpFileName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # lpFindFileData : WIN32_FIND_DATAW* out
  ],
  Fiddle::TYPE_VOIDP)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"
#[link(name = "kernel32")]
extern "system" {
    fn FindFirstFileW(
        lpFileName: *const u16,  // LPCWSTR
        lpFindFileData: *mut WIN32_FIND_DATAW  // WIN32_FIND_DATAW* out
    ) -> *mut core::ffi::c_void;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("KERNEL32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
public static extern IntPtr FindFirstFileW([MarshalAs(UnmanagedType.LPWStr)] string lpFileName, IntPtr lpFindFileData);
"@
$api = Add-Type -MemberDefinition $sig -Name 'KERNEL32_FindFirstFileW' -Namespace Win32 -PassThru
# $api::FindFirstFileW(lpFileName, lpFindFileData)
#uselib "KERNEL32.dll"
#func global FindFirstFileW "FindFirstFileW" wptr, wptr
; FindFirstFileW lpFileName, varptr(lpFindFileData)   ; 戻り値は stat
; lpFileName : LPCWSTR -> "wptr"
; lpFindFileData : WIN32_FIND_DATAW* out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
出力引数:
#uselib "KERNEL32.dll"
#cfunc global FindFirstFileW "FindFirstFileW" wstr, var
; res = FindFirstFileW(lpFileName, lpFindFileData)
; lpFileName : LPCWSTR -> "wstr"
; lpFindFileData : WIN32_FIND_DATAW* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
出力引数:
; HANDLE FindFirstFileW(LPCWSTR lpFileName, WIN32_FIND_DATAW* lpFindFileData)
#uselib "KERNEL32.dll"
#cfunc global FindFirstFileW "FindFirstFileW" wstr, var
; res = FindFirstFileW(lpFileName, lpFindFileData)
; lpFileName : LPCWSTR -> "wstr"
; lpFindFileData : WIN32_FIND_DATAW* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	kernel32 = windows.NewLazySystemDLL("KERNEL32.dll")
	procFindFirstFileW = kernel32.NewProc("FindFirstFileW")
)

// lpFileName (LPCWSTR), lpFindFileData (WIN32_FIND_DATAW* out)
r1, _, err := procFindFirstFileW.Call(
	uintptr(unsafe.Pointer(windows.StringToUTF16Ptr(lpFileName))),
	uintptr(lpFindFileData),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // HANDLE
function FindFirstFileW(
  lpFileName: PWideChar;   // LPCWSTR
  lpFindFileData: Pointer   // WIN32_FIND_DATAW* out
): THandle; stdcall;
  external 'KERNEL32.dll' name 'FindFirstFileW';
result := DllCall("KERNEL32\FindFirstFileW"
    , "WStr", lpFileName   ; LPCWSTR
    , "Ptr", lpFindFileData   ; WIN32_FIND_DATAW* out
    , "Ptr")   ; return: HANDLE
●FindFirstFileW(lpFileName, lpFindFileData) = DLL("KERNEL32.dll", "void* FindFirstFileW(char*, void*)")
# 呼び出し: FindFirstFileW(lpFileName, lpFindFileData)
# lpFileName : LPCWSTR -> "char*"
# lpFindFileData : WIN32_FIND_DATAW* out -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
# ※-W(Unicode)関数。なでしこ1はANSIのため -A 版の利用を推奨。
const std = @import("std");

extern "kernel32" fn FindFirstFileW(
    lpFileName: [*c]const u16, // LPCWSTR
    lpFindFileData: [*c]WIN32_FIND_DATAW // WIN32_FIND_DATAW* out
) callconv(std.os.windows.WINAPI) ?*anyopaque;
// Unicode(-W): UTF-16LE のヌル終端バッファ([*c]const u16)を渡す。
proc FindFirstFileW(
    lpFileName: WideCString,  # LPCWSTR
    lpFindFileData: ptr WIN32_FIND_DATAW  # WIN32_FIND_DATAW* out
): pointer {.importc: "FindFirstFileW", stdcall, dynlib: "KERNEL32.dll".}
# Unicode(-W): WideCString は newWideCString("...") で生成。
pragma(lib, "kernel32");
extern(Windows)
void* FindFirstFileW(
    const(wchar)* lpFileName,   // LPCWSTR
    WIN32_FIND_DATAW* lpFindFileData   // WIN32_FIND_DATAW* out
);
ccall((:FindFirstFileW, "KERNEL32.dll"), stdcall, Ptr{Cvoid},
      (Cwstring, Ptr{WIN32_FIND_DATAW}),
      lpFileName, lpFindFileData)
# lpFileName : LPCWSTR -> Cwstring
# lpFindFileData : WIN32_FIND_DATAW* out -> Ptr{WIN32_FIND_DATAW}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
# Unicode(-W): Cwstring には transcode(UInt16, "...") 等で UTF-16 を渡す。
local ffi = require("ffi")
ffi.cdef[[
void* FindFirstFileW(
    const uint16_t* lpFileName,
    void* lpFindFileData);
]]
local kernel32 = ffi.load("kernel32")
-- kernel32.FindFirstFileW(lpFileName, lpFindFileData)
-- lpFileName : LPCWSTR
-- lpFindFileData : WIN32_FIND_DATAW* out
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
-- Unicode(-W): uint16_t* には UTF-16LE のバッファ(ffi.new("uint16_t[?]", ...))を渡す。
const koffi = require('koffi');
const lib = koffi.load('KERNEL32.dll');
const FindFirstFileW = lib.func('__stdcall', 'FindFirstFileW', 'void *', ['str16', 'void *']);
// FindFirstFileW(lpFileName, lpFindFileData)
// lpFileName : LPCWSTR -> 'str16'
// lpFindFileData : WIN32_FIND_DATAW* out -> 'void *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("KERNEL32.dll", {
  FindFirstFileW: { parameters: ["buffer", "pointer"], result: "pointer" },
});
// lib.symbols.FindFirstFileW(lpFileName, lpFindFileData)
// lpFileName : LPCWSTR -> "buffer"
// lpFindFileData : WIN32_FIND_DATAW* out -> "pointer"
// 文字列は "buffer"。Unicode(-W) は new TextEncoder() ではなく UTF-16LE のバイト列(末尾に \x00\x00)を Uint8Array で渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
void* FindFirstFileW(
    const uint16_t* lpFileName,
    void* lpFindFileData);
C, "KERNEL32.dll");
// $ffi->FindFirstFileW(lpFileName, lpFindFileData);
// lpFileName : LPCWSTR
// lpFindFileData : WIN32_FIND_DATAW* out
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Kernel32 extends StdCallLibrary {
    Kernel32 INSTANCE = Native.load("kernel32", Kernel32.class, W32APIOptions.UNICODE_OPTIONS);
    Pointer FindFirstFileW(
        WString lpFileName,   // LPCWSTR
        Pointer lpFindFileData   // WIN32_FIND_DATAW* out
    );
}
// Unicode(-W): WString(入力)/char[](出力)で UTF-16 をマーシャリング。
@[Link("kernel32")]
lib LibKERNEL32
  fun FindFirstFileW = FindFirstFileW(
    lpFileName : UInt16*,   # LPCWSTR
    lpFindFileData : WIN32_FIND_DATAW*   # WIN32_FIND_DATAW* out
  ) : Void*
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef FindFirstFileWNative = Pointer<Void> Function(Pointer<Utf16>, Pointer<Void>);
typedef FindFirstFileWDart = Pointer<Void> Function(Pointer<Utf16>, Pointer<Void>);
final FindFirstFileW = DynamicLibrary.open('KERNEL32.dll')
    .lookupFunction<FindFirstFileWNative, FindFirstFileWDart>('FindFirstFileW');
// lpFileName : LPCWSTR -> Pointer<Utf16>
// lpFindFileData : WIN32_FIND_DATAW* out -> Pointer<Void>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function FindFirstFileW(
  lpFileName: PWideChar;   // LPCWSTR
  lpFindFileData: Pointer   // WIN32_FIND_DATAW* out
): THandle; stdcall;
  external 'KERNEL32.dll' name 'FindFirstFileW';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "FindFirstFileW"
  c_FindFirstFileW :: CWString -> Ptr () -> IO (Ptr ())
-- lpFileName : LPCWSTR -> CWString
-- lpFindFileData : WIN32_FIND_DATAW* out -> Ptr ()
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let findfirstfilew =
  foreign "FindFirstFileW"
    ((ptr uint16_t) @-> (ptr void) @-> returning (ptr void))
(* lpFileName : LPCWSTR -> (ptr uint16_t) *)
(* lpFindFileData : WIN32_FIND_DATAW* out -> (ptr void) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library kernel32 (t "KERNEL32.dll"))
(cffi:use-foreign-library kernel32)

(cffi:defcfun ("FindFirstFileW" find-first-file-w :convention :stdcall) :pointer
  (lp-file-name (:string :encoding :utf-16le))   ; LPCWSTR
  (lp-find-file-data :pointer))   ; WIN32_FIND_DATAW* out
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $FindFirstFileW = Win32::API::More->new('KERNEL32',
    'HANDLE FindFirstFileW(LPCWSTR lpFileName, LPVOID lpFindFileData)');
# my $ret = $FindFirstFileW->Call($lpFileName, $lpFindFileData);
# lpFileName : LPCWSTR -> LPCWSTR
# lpFindFileData : WIN32_FIND_DATAW* out -> LPVOID
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。
# Unicode(-W): LPCWSTR/LPWSTR は Win32::API が UTF-16 変換を行う。

関連項目

文字セット違い
類似 API
公式の関連項目
使用する型