NtCreateFile 関数 (ntifs.h)

[アーティクル]
05/24/2024

NtCreateFile ルーチンは、新しいファイルを作成するか、既存のファイルを開きます。

構文

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateFile(
  [out]          PHANDLE            FileHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [out]          PIO_STATUS_BLOCK   IoStatusBlock,
  [in, optional] PLARGE_INTEGER     AllocationSize,
  [in]           ULONG              FileAttributes,
  [in]           ULONG              ShareAccess,
  [in]           ULONG              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

パラメーター

[out] FileHandle

ファイルへのハンドルを受け取る HANDLE 変数へのポインター。

[in] DesiredAccess

オブジェクトへの要求されたアクセスを決定する ACCESS_MASK 値を指定します。

呼び出し元は、すべての種類のオブジェクトに対して定義されている 標準の アクセス権に加えて、次のいずれかの 特定の アクセス権を指定できます。つまり、ファイルに固有の権限です。

ACCESS_MASK フラグ	呼び出し元がこれを行うことを許可します
FILE_READ_DATA	ファイルからデータを読み取る。
FILE_READ_ATTRIBUTES	ファイルの属性を読み取ります。詳細については、FileAttributes パラメーターの説明を参照してください。
FILE_READ_EA	ファイルの拡張属性 (EA) を読み取ります。このフラグは、デバイスドライバーと中間ドライバーには関係ありません。
FILE_WRITE_DATA	ファイルにデータを書き込みます。
FILE_WRITE_ATTRIBUTES	ファイルの属性を書き込みます。詳細については、FileAttributes パラメーターの説明を参照してください。
FILE_WRITE_EA	ファイルの拡張属性 (EA) を変更します。このフラグは、デバイスドライバーと中間ドライバーには関係ありません。
FILE_APPEND_DATA	ファイルにデータを追加します。
FILE_EXECUTE	システムページング I/O を使用して、ファイルからメモリにデータを読み取ります。このフラグは、デバイスドライバーと中間ドライバーには関係ありません。

手記

ディレクトリを作成または開くときに、FILE_READ_DATA、FILE_WRITE_DATA、FILE_APPEND_DATA、またはFILE_EXECUTEを指定しないでください。

呼び出し元は、次の ジェネリック アクセス権 (すべてのオブジェクトの種類に適用される権限で、各ジェネリックアクセス権の意味がオブジェクト型に固有である) を指定することもできます。ファイルオブジェクトの一般的なアクセス権は、次の表に示すように、特定のアクセス権に対応します。 ("correspond" は "maps to" を意味し、ジェネリック権限の値がその特定の権限マッピングのビットごとの OR の値と "等しい" ことを意味しないことに注意してください)。 I/O マネージャーは、実際のマッピングを定義します。

汎用アクセス権	これらの特定のアクセス権にマップされます
GENERIC_READ	STANDARD_RIGHTS_READ、FILE_READ_DATA、FILE_READ_ATTRIBUTES、FILE_READ_EA、SYNCHRONIZE
GENERIC_WRITE	STANDARD_RIGHTS_WRITE、FILE_WRITE_DATA、FILE_WRITE_ATTRIBUTES、FILE_WRITE_EA、FILE_APPEND_DATA、SYNCHRONIZE
GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE、FILE_EXECUTE、FILE_READ_ATTRIBUTES、SYNCHRONIZE。この値は、デバイスドライバーと中間ドライバーには関係ありません。
GENERIC_ALL	FILE_ALL_ACCESS

手記

汎用アクセス権は、ファイルに対してのみ指定できます。ディレクトリに対して指定することはできません。

一部 CreateOptions フラグでは、NtCreateFile が呼び出されたときに、特定のアクセスフラグ DesiredAccess 設定する必要があります。これらの詳細については、CreateOptions パラメーターを参照してください。

たとえば、ファイルオブジェクトにGENERIC_READを指定した場合、ルーチンはこの値を特定のアクセス権のFILE_GENERIC_READビットマスクにマップします。前の表では、GENERIC_READに一覧表示されている特定のアクセス権は、FILE_GENERIC_READ ビットマスクに含まれるアクセスフラグに対応しています (ただし、等しくありません)。

ファイルが実際にディレクトリである場合、呼び出し元は次の一般的なアクセス権を指定することもできます。

DesiredAccess フラグをする	呼び出し元がこれを行うことを許可します
FILE_LIST_DIRECTORY	ディレクトリ内のファイルを一覧表示します。
FILE_TRAVERSE	ディレクトリを走査します。つまり、ディレクトリをファイルのパスに含めます。

アクセス権の詳細については、「アクセス権のACCESS_MASK と」を参照してください。

[in] ObjectAttributes

オブジェクト名とその他の属性を指定する OBJECT_ATTRIBUTES 構造体へのポインター。 InitializeObjectAttributes 使用して、この構造体を初期化します。呼び出し元がシステムスレッドコンテキストで実行されていない場合は、InitializeObjectAttributes呼び出すときにOBJ_KERNEL_HANDLE属性を設定する必要があります。

[out] IoStatusBlock

最終的な完了状態と、要求された操作に関するその他の情報を受け取る IO_STATUS_BLOCK 構造体へのポインター。特に、Information メンバーは、次のいずれかの値を受け取ります。

FILE_CREATED
FILE_OPENED
FILE_OVERWRITTEN
FILE_SUPERSEDED
FILE_EXISTS
FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

作成または上書きされたファイルの初期割り当てサイズ (バイト単位) を含むLARGE_INTEGERへのポインター。 AllocationSize が NULL場合、割り当てサイズは指定されません。ファイルが作成または上書きされていない場合、AllocationSize は無視されます。

[in] FileAttributes

1 つ以上のFILE_ATTRIBUTE_XXX フラグを指定します。これは、ファイルを作成または上書きするときに設定するファイル属性を表します。呼び出し元は通常、既定の属性を設定するFILE_ATTRIBUTE_NORMALを指定します。有効なFILE_ATTRIBUTE_XXX フラグの一覧については、Microsoft Windows SDK ドキュメントの CreateFile ルーチンを参照してください。ファイルが作成または上書きされていない場合、FileAttributes は無視されます。

[in] ShareAccess

0 または次のフラグの任意の組み合わせとして指定される共有アクセスの種類。

ShareAccess フラグの	他のスレッドがこれを行うことを許可します
FILE_SHARE_READ	ファイルを読み取る
FILE_SHARE_WRITE	ファイルを書き込む
FILE_SHARE_DELETE	ファイルを削除する

通常、デバイスドライバーと中間ドライバー ShareAccess を 0 に設定します。これによって、呼び出し元は開いているファイルに排他的にアクセスできます。

[in] CreateDisposition

ファイルが存在する場合、または存在しない場合に実行するアクションを指定します。 CreateDisposition 、次の表のいずれかの値を指定できます。

CreateDisposition 値をする	ファイルが存在する場合のアクション	ファイルが存在しない場合のアクション
FILE_SUPERSEDE	ファイルを置き換えます。	ファイルを作成します。
FILE_CREATE	エラーを返します。	ファイルを作成します。
FILE_OPEN	ファイルを開きます。	エラーを返します。
FILE_OPEN_IF	ファイルを開きます。	ファイルを作成します。
FILE_OVERWRITE	ファイルを開き、上書きします。	エラーを返します。
FILE_OVERWRITE_IF	ファイルを開き、上書きします。	ファイルを作成します。

[in] CreateOptions

ドライバーがファイルを作成または開くときに適用するオプションを指定します。次の表の 1 つ以上のフラグを使用します。

CreateOptions フラグ	意味
FILE_DIRECTORY_FILE (0x00000001)	ファイルはディレクトリです。互換性のある CreateOptions フラグは、FILE_SYNCHRONOUS_IO_ALERT、FILE_SYNCHRONOUS_IO_NONALERT、FILE_WRITE_THROUGH、FILE_OPEN_FOR_BACKUP_INTENT、およびFILE_OPEN_BY_FILE_IDです。 CreateDisposition パラメーターは、FILE_CREATE、FILE_OPEN、またはFILE_OPEN_IFに設定する必要があります。
FILE_WRITE_THROUGH (0x00000002)	システムサービス、ファイルシステムドライバー、およびファイルにデータを書き込むドライバーは、要求された書き込み操作が完了したと見なされる前に、実際にデータをファイルに転送する必要があります。
FILE_SEQUENTIAL_ONLY (0x00000004)	ファイルへのアクセスはすべて順次行われます。
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008)	ファイルは、ドライバーの内部バッファーにキャッシュまたはバッファーすることはできません。このフラグは、DesiredAccess パラメーターのFILE_APPEND_DATA フラグと互換性がありません。
FILE_SYNCHRONOUS_IO_ALERT (0x00000010)	ファイルに対するすべての操作は同期的に実行されます。呼び出し元に代わって待機すると、アラートが早期に終了する可能性があります。また、このフラグにより、I/O システムはファイル位置ポインターを維持します。このフラグを設定する場合は、DesiredAccess パラメーターで SYNCHRONIZE フラグを設定する必要があります。
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020)	ファイルに対するすべての操作は同期的に実行されます。 I/O キューと完了を同期するシステムでの待機は、アラートの対象になりません。また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。このフラグを設定する場合は、DesiredAccess パラメーターで SYNCHRONIZE フラグを設定する必要があります。
FILE_NON_DIRECTORY_FILE (0x00000040)	ファイルはディレクトリされていません。開くファイルオブジェクトは、データファイルを表すことができます。論理デバイス、仮想デバイス、または物理デバイス。またはボリューム。 Windows 11 バージョン 24H2 以降、NTFS では、$INDEX_ALLOCATION 属性を開くときにこのフラグが適用されるようになりました。
FILE_CREATE_TREE_CONNECTION (0x00000080)	ネットワーク経由で開くために、このファイルのツリー接続を作成します。このフラグは、デバイスドライバーと中間ドライバーでは使用されません。
FILE_COMPLETE_IF_OPLOCKED (0x00000100)	呼び出し元のスレッドをブロックするのではなく、ターゲットファイルが操作されている場合は、STATUS_OPLOCK_BREAK_IN_PROGRESSの代替成功コードを使用して、この操作をすぐに完了します。ファイルが操作されている場合、別の呼び出し元は既にファイルにアクセスできます。このフラグは、デバイスドライバーと中間ドライバーでは使用されません。
FILE_NO_EA_KNOWLEDGE (0x00000200)	開かれている既存のファイルの拡張属性 (EA) が、呼び出し元がファイルを正しく解釈するために EA を理解する必要があることを示している場合、ntCreateFile はエラーを返す必要があります。このフラグは、デバイスドライバーと中間ドライバーには関係ありません。
FILE_OPEN_REMOTE_INSTANCE (0x00000400)	システム用に予約されています。使用しないでください。
FILE_RANDOM_ACCESS (0x00000800)	ファイルへのアクセスはランダムにできるため、ファイルシステムドライバーまたはシステムによって順次先読み操作を実行する必要はありません。
FILE_DELETE_ON_CLOSE (0x00001000)	システムは、ファイルへの最後のハンドルが NtCloseに渡されたときにファイルを削除します。このフラグが設定されている場合は、DesiredAccess パラメーターで DELETE フラグを設定する必要があります。
FILE_OPEN_BY_FILE_ID (0x00002000)	ObjectAttributes パラメーターで指定されたファイル名には、ファイルシステムに応じて、ファイルのバイナリ 8 バイトまたは 16 バイトのファイル参照番号またはオブジェクト ID が含まれます。必要に応じて、デバイス名の後に円記号を付けて、これらのバイナリ値を続行できます。詳細と例については、「解説」を参照してください。
FILE_OPEN_FOR_BACKUP_INTENT (0x00004000)	ファイルがバックアップインテント用に開かれています。そのため、システムは、ファイルのセキュリティ記述子に対して desiredAccess パラメーター確認する前に、特定のアクセス権を確認し、呼び出し元にファイルへの適切なアクセス権を付与する必要があります。このフラグは、デバイスドライバーと中間ドライバーでは使用されません。
FILE_NO_COMPRESSION (0x00008000)	親ディレクトリからのFILE_ATTRIBUTE_COMPRESSEDの継承を抑制します。これにより、圧縮されていないファイルを圧縮済みとしてマークされたディレクトリに作成できます。
FILE_OPEN_REQUIRING_OPLOCK (0x00010000)	ファイルが開き、ファイルの日和見ロック (oplock) が 1 つのアトミック操作として要求されています。ファイルシステムは、作成操作を実行する前に oplock をチェックし、結果が既存の oplock を中断する場合は、STATUS_CANNOT_BREAK_OPLOCKのリターンコードで作成を失敗します。このフラグは、Windows 7 および Windows Server 2008 R2 以降で使用できます。
FILE_DISALLOW_EXCLUSIVE (0x00020000)	既存のファイルを開くときに、FILE_SHARE_READが指定されておらず、ファイルシステムのアクセスチェックで呼び出し元にファイルへの書き込みアクセスが許可されない場合は、STATUS_ACCESS_DENIEDでこのファイルを開けませんでした。これは、Windows 7 より前の既定の動作でした。このフラグは、Windows 7 および Windows Server 2008 R2 以降で使用できます。
FILE_SESSION_AWARE (0x00040000)	ファイルまたはデバイスを開くクライアントはセッションに対応しており、必要に応じてセッションごとのアクセスが検証されます。このフラグは、Windows 8 以降で使用できます。
FILE_RESERVE_OPFILTER (0x00100000)	このフラグを使用すると、アプリケーションはフィルターの日和見ロック (oplock) を要求して、他のアプリケーションが共有違反を受け取らないようにすることができます。既に開いているハンドルがある場合、作成要求はSTATUS_OPLOCK_NOT_GRANTEDで失敗します。詳細については、次の「解説」セクションを参照してください。
FILE_OPEN_REPARSE_POINT (0x00200000)	再解析ポイントを使用してファイルを開き、ファイルの通常の再解析ポイント処理をバイパスします。詳細については、次の「解説」セクションを参照してください。
FILE_OPEN_NO_RECALL (0x00400000)	オフラインストレージまたは仮想化を実行するフィルターに対して、このファイルが開かれた結果としてファイルの内容が再呼び出されないように指示します。
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000)	このフラグは、呼び出し元のスレッドに関連付けられているユーザーをキャプチャするようにファイルシステムに指示します。返されたハンドルを使用して FltQueryVolumeInformation または ZwQueryVolumeInformationFile への後続の呼び出しでは、呼び出し元が使用できる空き領域を計算するために、その時点で呼び出し元ユーザーではなく、キャプチャされたユーザーが想定されます。これは、次の FsInformationClass 値に適用されます: FileFsSizeInformation、FileFsFullSizeInformation、および FileFsFullSizeInformationEx。
FILE_CONTAINS_EXTENDED_CREATE_INFORMATION (0x10000000)	EaBuffer パラメーターを EXTENDED_CREATE_INFORMATIONのインスタンスとして解釈します。このフラグは、Windows 11 バージョン 22H2 以降で使用できます。

[in, optional] EaBuffer

デバイスドライバーと中間ドライバーの場合、このパラメーターは NULL ポインターである必要があります。

[in] EaLength

デバイスドライバーと中間ドライバーの場合、このパラメーターは 0 である必要があります。

戻り値

NtCreateFile は、成功した場合はSTATUS_SUCCESSを返し、失敗した場合は適切な NTSTATUS エラーコードを返します。後者の場合、呼び出し元は、IoStatusBlock パラメーターを確認することで、エラーの原因を特定できます。

手記

NtCreateFile は、戻り値として、または IoStatusBlock パラメーターによって指される IO_STATUS_BLOCK 構造体の Status メンバーでSTATUS_FILE_LOCK_CONFLICTを返す場合があります。これは、NTFS ログファイルがいっぱいで、NtCreateFile がこの状況の処理を試みている間にエラーが発生した場合にのみ発生します。

備考

NtCreateFile は、呼び出し元がファイルのデータ、またはファイルオブジェクトの状態と属性を操作するために使用できるハンドルを提供します。詳細については、「ドライバーでファイルを使用する」を参照してください。

FileHandle が指すハンドルが使用されなくなったら、ドライバーは NtClose 呼び出して閉じる必要があります。

呼び出し元がシステムスレッドコンテキストで実行されていない場合は、作成するハンドルがプライベートハンドルであることを確認する必要があります。それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってハンドルにアクセスできます。詳細については、「オブジェクトハンドル」を参照してください。

NtCreateFileを使用して作成または開くファイルの名前指定するには、次の 2 つの方法があります。

完全修飾パス名として、入力 ObjectAttributes の ObjectName メンバーで指定されます。
入力 ObjectAttributesの RootDirectory メンバー内のハンドルによって表されるディレクトリファイルを基準とするパス名。

DesiredAccess パラメーターに特定のフラグを設定すると、次の効果が得られます。

呼び出し元が、返された FileHandleを待機して I/O 完了を同期するには、SYNCHRONIZE フラグを設定する必要があります。それ以外の場合、デバイスまたは中間ドライバーである呼び出し元は、イベントオブジェクトを使用して I/O 完了を同期する必要があります。
呼び出し元が FILE_APPEND_DATA フラグと SYNCHRONIZE フラグのみを設定すると、ファイルの末尾にのみ書き込み可能になり、ファイルへの書き込み操作に関するオフセット情報は無視されます。この種類の操作では、必要に応じてファイルが自動的に拡張されます。
ファイルのFILE_WRITE_DATA フラグを設定すると、呼び出し元はファイルの末尾を超えて書き込むこともできます。ここでも、ファイルは必要に応じて自動的に拡張されます。
呼び出し元が FILE_EXECUTE フラグと SYNCHRONIZE フラグのみを設定した場合、返された FileHandleを使用して、ファイルにデータを直接読み書きすることはできません。つまり、ファイルに対するすべての操作は、命令操作とデータアクセス操作に応答してシステムポケットベルを介して行われます。デバイスドライバーと中間ドライバーは、FILE_EXECUTE フラグを設定しないでください。

ShareAccess パラメーターは、個別のスレッドが同じファイルに同時にアクセスできるかどうかを決定します。両方の呼び出し元が適切なアクセス特権を持っている場合は、ファイルを正常に開いて共有できます。 NtCreateFile の元の呼び出し元がFILE_SHARE_READ、FILE_SHARE_WRITE、またはFILE_SHARE_DELETEを指定しない場合、他の呼び出し元はファイルを開けなくなります。つまり、元の呼び出し元には排他的アクセスが許可されます。

共有ファイルを正常に開くには、DesiredAccess フラグは、まだリリースされていない以前の開いているすべての操作の DesiredAccess および ShareAccess フラグと互換性がある必要があります。つまり、特定のファイルの NtCreateFile をするために指定された DesiredAccess は、ファイルの他のオープナーが許可していないアクセスと競合してはなりません。

CreateDisposition 値FILE_SUPERSEDE、呼び出し元が既存のファイルオブジェクトに対する DELETE アクセス権を持っている必要があります。その場合、既存のファイルのFILE_SUPERSEDEを使用して NtCreateFile を正常に呼び出すと、そのファイルが実質的に削除され、再作成されます。これは、ファイルが既に別のスレッドによって開かれている場合は、FILE_SHARE_DELETE フラグを設定して ShareAccess パラメーターを指定してファイルを開くことを意味します。この種類の処理は、ファイルを上書きする POSIX スタイルと一致することに注意してください。

CreateDisposition 値FILE_OVERWRITE_IFとFILE_SUPERSEDEは似ています。 NtCreateFile が既存のファイルで呼び出され、これらの CreateDisposition 値のいずれかで呼び出された場合、ファイルは置き換えられます。

ファイルの上書きは、次を除き、置き換え操作と意味的に同等です。

呼び出し元は、削除アクセスではなく、ファイルへの書き込みアクセス権を持っている必要があります。これは、ファイルが既に別のスレッドによって開かれている場合は、ShareAccessの入力 FILE_SHARE_WRITE フラグを設定してファイルを開くことを意味します。
指定されたファイル属性は、論理的には ORed であり、ファイルに既に存在します。これは、ファイルが既に別のスレッドによって開かれている場合、NtCreateFile の後続の呼び出し元は、既存の FileAttributes フラグを無効にすることはできませんが、同じファイルに対して追加のフラグを有効にできることを意味します。このファイルの上書きスタイルは、MS-DOS、Microsoft Windows 3.1、OS/2 と一致することに注意してください。

FILE_DIRECTORY_FILE CreateOptions 値は、作成または開くファイルがディレクトリであることを指定します。ディレクトリファイルが作成されると、ファイルシステムはディスク上に適切な構造を作成し、その特定のファイルシステムのディスク上構造の空のディレクトリを表します。このオプションが指定されていて、開く指定されたファイルがディレクトリファイルでない場合、または呼び出し元が CreateOptions または CreateDisposition 値不整合指定した場合、NtCreateFile 呼び出しは失敗します。

FILE_NO_INTERMEDIATE_BUFFERING CreateOptions フラグを指定すると、ファイルシステムが呼び出し元に代わって中間バッファリングを実行できなくなります。このフラグを指定すると、呼び出し元のパラメーターが他の ZwXxxFile ルーチンに制限されます。

オプションの ByteOffset ntReadFile または NtWriteFile に渡されるは、セクターサイズの倍数である必要があります。
NtReadFile または NtWriteFile に渡される長は、セクターサイズの整数である必要があります。長さがセクターサイズであるバッファーに対して読み取り操作を指定すると、転送中にファイルの末尾に達した場合に、そのバッファーに転送される有効バイト数が少なくなる可能性があることに注意してください。
バッファーは、基になるデバイスの配置要件に従って配置する必要があります。この情報を取得するには、NtCreateFile を呼び出して、物理デバイスを表すファイルオブジェクトのハンドルを取得し、そのハンドルを NtQueryInformationFile渡します。システムのFILE_XXX_ALIGNMENT 値の一覧については、DEVICE_OBJECTを参照してください。
FileInformationClass パラメーターを filePositionInformation に設定して ntSetInformationFile をする呼び出しでは、セクターサイズの倍数であるオフセットを指定する必要があります。

FILE_SYNCHRONOUS_IO_ALERTおよび FILE_SYNCHRONOUS_IO_NONALERT CreateOptions フラグ (相互に排他的) は、返された fileHandleによって参照されるファイルオブジェクトを介して操作が行われる限り、ファイルに対するすべての I/O 操作が同期的であることを指定します。このようなファイルのすべての I/O は、返されたハンドルを使用して、すべてのスレッドでシリアル化されます。これらの CreateOptions フラグのいずれかが設定されている場合は、SYNCHRONIZE DesiredAccess フラグも設定して、I/O マネージャーがファイルオブジェクトを同期オブジェクトとして使用するように強制する必要があります。このような場合、I/O マネージャーは現在のファイル位置オフセットを追跡します。このオフセットは、NtReadFile に渡して NtWriteFileできます。 NtQueryInformationFile 呼び出すか、NtSetInformationFile をして、この位置を取得または設定します。

CreateOptions FILE_OPEN_REPARSE_POINT フラグが指定されず、NtCreateFile が再解析ポイントを使用してファイルを開こうと場合、ファイルに対して通常の再解析ポイント処理が行われます。一方、FILE_OPEN_REPARSE_POINT フラグが指定されている場合、通常の再解析処理発生せず、NtCreateFile 再解析ポイントファイルを直接開こうとします。いずれの場合も、開いている操作が成功した場合、NtCreateFile はSTATUS_SUCCESSを返します。それ以外の場合、ルーチンは NTSTATUS エラーコードを返します。 NtCreateFile はSTATUS_REPARSEを返しません。

CreateOptions FILE_OPEN_REQUIRING_OPLOCK フラグを使用すると、ファイルを開いて、サードパーティがファイルを開いて共有違反を受け取る可能性がある oplock を要求する時間が短縮されます。アプリケーションでは、NtCreateFile で FILE_OPEN_REQUIRING_OPLOCK フラグ使用し、任意の oplock を要求できます。これにより、共有違反の原因となる後続のオープン要求が oplock 所有者に通知されます。

Windows 7 では、アプリケーションが FILE_OPEN_REQUIRING_OPLOCK フラグを使用するときにファイルに他のハンドルが存在する場合、作成操作はSTATUS_OPLOCK_NOT_GRANTEDで失敗します。この制限は、Windows 8 以降では存在しなくなりました。

この作成操作によって、ファイルに既に存在する oplock が中断される場合、FILE_OPEN_REQUIRING_OPLOCK フラグを設定すると、作成操作はSTATUS_CANNOT_BREAK_OPLOCKで失敗します。この作成操作では、既存の oplock は破損しません。

FILE_OPEN_REQUIRING_OPLOCK フラグを使用するアプリケーションは、この呼び出しが成功した後に oplock を要求する必要があります。または、通常の oplock 処理の利点なしに、ファイルを開こうとするすべての試行がブロックされます。同様に、この呼び出しが成功しても後続の oplock 要求が失敗した場合、このフラグを使用するアプリケーションは、oplock 要求が失敗したことを検出した後でハンドルを閉じる必要があります。アプリケーションは、(ファイルハンドルを閉じる以外に) oplock を要求する前に、ファイルに対して他のファイルシステム操作を実行しないでください。そうしないと、デッドロックが発生する可能性があります。

手記

FILE_OPEN_REQUIRING_OPLOCK フラグは、Windows 7、Windows Server 2008 R2 以降の Windows オペレーティングシステムで使用できます。 Windows 7 でこのフラグを実装する Microsoft ファイルシステムは、NTFS、FAT、exFAT です。

CreateOptions フラグFILE_RESERVE_OPFILTERを使用すると、アプリケーションはレベル 1、バッチ、またはフィルター操作を要求して、他のアプリケーションが共有違反を受け取らないようにすることができます。ただし、FILE_RESERVE_OPFILTERは、フィルター操作の場合にのみ実際に役立ちます。これを使用するには、次の手順を実行する必要があります。

FILE_RESERVE_OPFILTER CreateOptions を使用して作成要求を発行し、正確にFILE_READ_ATTRIBUTESの DesiredAccess を
し、正確にFILE_SHARE_READの ShareAccess を
|FILE_SHARE_WRITE |FILE_SHARE_DELETE。
- 既に開いているハンドルがある場合、作成要求はSTATUS_OPLOCK_NOT_GRANTEDで失敗し、次に要求された oplock も失敗します。
- より多くのアクセス権または少ない共有で開くと、STATUS_OPLOCK_NOT_GRANTEDのエラーも発生します。
作成要求が成功した場合は、oplock を要求します。
ファイルへの別のハンドルを開いて I/O を実行します。

手順 3 では、フィルター操作ロックに対してのみこれを実用的にします。手順 3 で開いたハンドルには、最大FILE_READ_ATTRIBUTESを含む DesiredAccess を含めることができます。FILE_WRITE_ATTRIBUTES |FILE_READ_DATA |FILE_READ_EA |FILE_EXECUTE |SYNCHRONIZE |READ_CONTROLし、フィルター操作ロックを中断しません。ただし、DesiredAccess FILE_READ_ATTRIBUTES より大きい |FILE_WRITE_ATTRIBUTES |SYNCHRONIZE では、レベル 1 またはバッチのオペロックが解除され、FILE_RESERVE_OPFILTER フラグはそれらの oplock 型では使用できなくなります。

NTFS は、FILE_RESERVE_OPFILTERを実装する唯一の Microsoft ファイルシステムです。

CreateOptions FILE_OPEN_BY_FILE_ID フラグの場合、デバイス名の例の形式は次のようになります。

\??\C:\<FileID>
\device\HardDiskVolume1\<ObjectID>

ここで、FileID は 8 バイトで、ObjectID は 16 バイトです。

NTFS では、8 バイトまたは 16 バイトの参照番号またはオブジェクト ID を指定できます。 16 バイトの参照番号は、ゼロで埋め込まれた 8 バイトの数値と同じです。
ReFS では、8 バイトまたは 16 バイトの参照番号を指定できます。 16 バイトの数値は、8 バイトの数値とは関係ありません。オブジェクト ID はサポートされていません。
FAT、ExFAT、UDFS、および CDFS ファイルシステムは、FILE_OPEN_BY_FILE_ID フラグをサポートしていません。

この番号は、特定のファイルシステムによって割り当てられ、特定のファイルシステムに固有です。ファイル名フィールドには部分的にバイナリ BLOB が含まれるため、これが有効な Unicode 文字列であると想定するのは正しくありません。さらに重要なのは、null で終わる文字列ではない可能性があります。

NtCreateFile の呼び出し元は、IRQL = PASSIVE_LEVEL で実行され、特殊なカーネル API が有効になっている必要があります。

手記

この関数の呼び出しがユーザーモードで発生する場合は、"ZwCreateFile" の代わりに "NtCreateFile"名前を使用する必要があります。

カーネルモードドライバーからの呼び出しの場合、Windows ネイティブシステムサービスルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。ルーチンの NtXxx と ZwXxx バージョンの間の関係の詳細については、「ネイティブシステムサービスルーチンの Nt および Zw バージョンの使用を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows 2000
ターゲットプラットフォームの	万国
ヘッダー	ntifs.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
ライブラリ	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則をする	HwStorPortProhibitedDIs、PowerIrpDDis

次の方法で共有

NtCreateFile 関数 (ntifs.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース