NtCreateFile 関数 (winternl.h)
新しいファイルまたはディレクトリを作成するか、既存のファイル、デバイス、ディレクトリ、またはボリュームを開きます。
この関数は、Windows Driver Kit (WDK) に記載されている ZwCreateFile 関数と同等のユーザー モードです。
構文
__kernel_entry 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] PVOID EaBuffer,
[in] ULONG EaLength
);
パラメーター
[out] FileHandle
呼び出しが成功した場合にファイル ハンドルを受け取る変数へのポインター。
[in] DesiredAccess
呼び出し元がファイルまたはディレクトリに対して必要とするアクセスの種類を表す ACCESS_MASK 値。 DesiredAccess フラグ
NtCreateFile の呼び出し元は、ディレクトリ ファイルを表さないファイル オブジェクトに対して、ビットごとの OR と、前述の DesiredAccess フラグ リストからの互換性のあるフラグを追加で使用して、次の 1 つまたは複数の組み合わせを指定できます。
FILE_GENERIC_EXECUTE 値は、デバイスドライバーと中間ドライバーには関係ありません。
STANDARD_RIGHTS_XXX は、システム オブジェクトにセキュリティを適用するために使用される定義済みのシステム値です。
CreateOptions パラメーターで示されているように、ディレクトリ ファイルを開いたり作成したりするには、NtCreateFile の呼び出し元は、ビットごとの OR と、前述の DesiredAccess フラグ リストの 1 つ以上の互換性のあるフラグを使用して、次の 1 つまたは複数の組み合わせを指定できます。
価値 | 意味 |
---|---|
|
ディレクトリ内のファイルを一覧表示できます。 |
|
ディレクトリは走査できます。つまり、ファイルのパス名の一部にすることができます。 |
[in] ObjectAttributes
InitializeObjectAttributesで既
価値 | 意味 |
---|---|
|
指定されたデータ ObjectAttributes バイト数を指定します。 この値は、少なくとも sizeof(OBJECT_ATTRIBUTES) である必要があります。 |
|
必要に応じて、NtCreateFileの前の呼び出しによって取得されたディレクトリへのハンドルを指定します。 この値が NULL |
|
作成または開くファイルの名前を指定するバッファー内の Unicode 文字列を指します。 この値は、rootDirectoryで指定されたディレクトリに対する相対ファイル名でない限り、完全修飾ファイル指定またはデバイス オブジェクトの名前 |
|
ファイル オブジェクト属性を制御するフラグのセットです。 この値は 0 または OBJ_CASE_INSENSITIVEにすることができます。これは、名前参照コードが完全一致検索を実行するのではなく、ObjectName メンバーの大文字と小文字を無視する必要があることを示します。 OBJ_INHERIT 値は、デバイスドライバーと中間ドライバーとは無関係です。 |
|
必要に応じて、ファイルに適用するセキュリティ記述子を指定します。 このようなセキュリティ記述子で指定された ACL は、作成時にのみファイルに適用されます。 ファイルの作成時に値が null |
|
サーバーがクライアントのセキュリティ コンテキストに与える必要があるアクセス権を指定します。 この値は、保護されたサーバーへの接続が確立された場合にのみ、NULL です。これにより、呼び出し元は、呼び出し元のセキュリティ コンテキストのどの部分をサーバーで使用できるか、およびサーバーが呼び出し元の偽装を許可されるかどうかを制御できます。 |
[out] IoStatusBlock
最終的な完了状態と要求された操作に関する情報を受け取る変数へのポインター。 NtCreateFile
- FILE_CREATED
- FILE_OPENED
- FILE_OVERWRITTEN
- FILE_SUPERSEDED
- FILE_EXISTS
- FILE_DOES_NOT_EXIST
[in, optional] AllocationSize
ファイルの初期割り当てサイズ (バイト単位)。 0 以外の値は、ファイルが作成、上書き、または置き換えられている場合を除き、効果はありません。
[in] FileAttributes
ファイル属性。 明示的に指定された属性は、ファイルが作成、置き換えられる、または場合によっては上書きされる場合にのみ適用されます。 既定では、この値は FILE_ATTRIBUTE_NORMALであり、Wdm.h および NtDdk.h で定義されている 1 つ以上の FILE_ATTRIBUTE_xxxx フラグの ORed の組み合わせによってオーバーライドできます。
[in] ShareAccess
呼び出し元がファイルで使用する共有アクセスの種類。0、または次の値の 1 つまたは組み合わせとして使用します。
詳細については、Windows SDK を参照してください。
[in] CreateDisposition
ファイルが既に存在するかどうかに応じて、次のいずれかの値として実行する処理を指定します。
[in] CreateOptions
次のフラグの互換性のある組み合わせとして、ファイルを作成または開くときに適用するオプション。
[in] EaBuffer
拡張属性を渡すために使用される EA バッファーへのポインター。
[in] EaLength
EA バッファーの長さ。
戻り値
NtCreateFile
備考
NtCreateFileによって指定されたハンドルは、後続の呼び出しでファイル内のデータまたはファイル オブジェクトの状態または属性を操作するために使用できます。
NtCreateFileを使用して作成または開くファイルの名前
- 完全修飾パス名として、入力 ObjectAttributes の ObjectName メンバーで指定されます。
- 入力 ObjectAttributes の RootDirectory メンバー内のハンドルによって表されるディレクトリ ファイルに対する相対パス名として
特定の DesiredAccess フラグとフラグの組み合わせには、次の効果があります。
- 呼び出し元が返された FileHandleを待機して I/O 完了を同期するには、SYNCHRONIZE フラグを設定する必要があります。
- DesiredFlags
に 0 を渡すことは無効です。 - FILE_APPEND_DATA と SYNCHRONIZE フラグのみが設定されている場合、呼び出し元はファイルの末尾にのみ書き込むことができます。ファイルへの書き込みに関するオフセット情報は無視されます。 ただし、この種類の書き込み操作では、必要に応じてファイルが自動的に拡張されます。
- ファイルの FILE_WRITE_DATA フラグを設定すると、ファイルの末尾を超える書き込みも行われます。 ファイルは、この種類の書き込み用にも自動的に拡張されます。
- FILE_EXECUTE と SYNCHRONIZE フラグのみが設定されている場合、呼び出し元は、返された FileHandleを使用してファイル内のデータを直接読み書きすることはできません。つまり、命令とデータ アクセスに応答して、ファイルに対するすべての操作がシステム ページャーを介して実行されます。
ShareAccess パラメーターは、個別のスレッドが同じファイルに同時にアクセスできるかどうかを決定します。 指定した方法でファイルにアクセスする権限を両方のファイルオーナーに付与すれば、ファイルを正常に開いて共有できます。 NtCreateFile の元の呼び出し元が FILE_SHARE_READ、FILE_SHARE_WRITE、または FILE_SHARE_DELETEを指定していない場合は、ファイルに対して他の開いている操作を実行できません。つまり、元の呼び出し元には、ファイルへの排他的アクセス権が付与されます。
共有ファイルを正常に開くには、ファイルに対して要求された DesiredAccess パラメーターが、の DesiredAccessと、NtCloseでまだリリースされていない前述のすべてのオープンの ShareAccess 仕様の両方と互換性がある必要があります。 つまり、特定のファイルの NtCreateFile を
この種類の処理は、ファイルを上書きする POSIX スタイルと一致することに注意してください。 CreateDisposition の値 FILE_OVERWRITE_IF と FILE_SUPERSEDE は似ています。 ZwCreateFile が既存のファイルで呼び出され、これらの CreateDisposition 値のいずれかで呼び出された場合、ファイルは置き換えられます。
ファイルの上書きは、次を除き、置き換え操作と意味的に同等です。
- 呼び出し元は、削除アクセスではなく、ファイルへの書き込みアクセス権を持っている必要があります。 これは、ファイルが既に別のスレッドによって開かれている場合、ShareAccess パラメーターの入力
FILE_SHARE_WRITE フラグを設定してファイルを開くことを意味します。 - 指定されたファイル属性は、論理的には ORed であり、ファイルに既に存在します。 これは、ファイルが既に別のスレッドによって開かれている場合、NtCreateFile の後続の呼び出し元は、既存の FileAttributes フラグを無効にすることはできませんが、同じファイルに対して追加のフラグを有効にできることを意味します。 このファイルの上書きスタイルは、MS-DOS、Windows 3.1、OS/2 オペレーティング システムと一致することに注意してください。
CreateOptionsFILE_DIRECTORY_FILE 値は、作成または開くファイルがディレクトリ ファイルであることを指定します。 ディレクトリ ファイルが作成されると、ファイル システムはディスク上に適切な構造を作成し、その特定のファイル システムのディスク上構造の空のディレクトリを表します。 このオプションが指定されていて、開く指定されたファイルがディレクトリ ファイルでない場合、または呼び出し元が CreateOptions または CreateDisposition 値
CreateOptionsFILE_NO_INTERMEDIATE_BUFFERING フラグを指定すると、ファイル システムは呼び出し元に代わって中間バッファリングを実行できなくなります。 この値を指定すると、呼び出し元のパラメーターが、次のような他の NtXXXFile ルーチンに制限されます。
- オプションの
ByteOffset 、NtReadFile または ntWriteFile 関数に渡される場合は、セクター サイズの整数である必要があります。 NtReadFile または ntWriteFileに渡される 長 は、セクター サイズの整数である必要があります。 長さがセクター サイズであるバッファーに対して読み取り操作を指定すると、転送中にファイルの末尾に達した場合に、そのバッファーに転送される有効バイト数が少なくなる可能性があることに注意してください。- バッファーは、基になるデバイスの配置要件に従って調整する必要があります。 この情報を取得するには、NtCreateFile を呼び出して、物理デバイスを表すファイル オブジェクトのハンドルを取得し、そのハンドルで NtQueryInformationFile を呼び出します。 XXX
_ALIGNMENT 値FILE_ システムの一覧については、Windows SDK のドキュメントを参照してください。 FileInformationClass パラメーターを filePositionInformation に設定して ntSetInformationFile をする呼び出しでは、セクター サイズの整数であるオフセットを指定する必要があります。
CreateOptions パラメーターの FILE_OPEN_REQUIRING_OPLOCK フラグを使用すると、ファイルを開いて、サード パーティがファイルを開くことができる可能性がある oplock を要求してから、共有違反が発生する可能性がある時間が短縮されます。 アプリケーションは、ntCreateFile
Windows 7 では、アプリケーションがこのフラグを使用するときにファイルに他のハンドルが存在する場合、作成操作は STATUS_OPLOCK_NOT_GRANTEDで失敗します。 この制限は、Windows 8 以降では存在しなくなりました。
この作成操作によって、ファイルに既に存在する oplock が中断される場合、FILE_OPEN_REQUIRING_OPLOCK フラグを設定すると、STATUS_CANNOT_BREAK_OPLOCKで作成操作が失敗します。 この作成操作では、既存の oplock は破損しません。
このフラグを使用するアプリケーションは、この呼び出しが成功した後に oplock を要求する必要があります。または、通常の oplock 処理の利点なしに、ファイルを開こうとするすべての試行がブロックされます。 同様に、この呼び出しが成功しても後続の oplock 要求が失敗した場合、このフラグを使用するアプリケーションは、oplock 要求が失敗したことを検出した後でハンドルを閉じる必要があります。
CreateOptions パラメーターの FILE_RESERVE_OPFILTER フラグを使用すると、アプリケーションはレベル 1、バッチ、またはフィルター 操作を要求して、他のアプリケーションが共有違反を受け取らないようにすることができます。 ただし、実際的には、FILE_RESERVE_OPFILTER はフィルター 操作に対してのみ役立ちます。 これを使用するには、次の手順を実行する必要があります。
- CreateOptions
FILE_RESERVE_OPFILTER 、DesiredAccess の正確なFILE_READ_ATTRIBUTES 、および正確にの ShareAccess を して作成要求を発行します。 考えられるエラーは次のとおりです。 - 既に開いているハンドルがある場合、作成要求は STATUS_OPLOCK_NOT_GRANTEDで失敗し、次に要求された oplock も失敗します。
-
FILE_READ_ATTRIBUTES より多くのアクセス権を持つか、
(FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE)
よりも少ない共有で開くと、要求は STATUS_OPLOCK_NOT_GRANTEDで失敗します。
- 作成要求が成功した場合は、oplock を要求します。
- ファイルへの別のハンドルを開いて I/O を実行します。
(FILE_READ_ATTRIBUTES | FILE_WRITE_ATTRIBUTES | FILE_READ_DATA | FILE_READ_EA | FILE_EXECUTE | SYNCHRONIZE | READ_CONTROL)
を含み、フィルター 操作を中断しない DesiredAccess を含めることができます。 ただし、DesiredAccessNTFS は、FILE_RESERVE_OPFILTERを実装する唯一の Microsoft ファイル システムです。
oplock の詳細については、「opportunistic Locks
WDK ヘッダー ファイル NtDef.h は、多くの定数定義と、InitializeObjectAttributes マクロに必要であることに注意してください。
必要条件
要件 | 価値 |
---|---|
ターゲット プラットフォーム の |
ウィンドウズ |
ヘッダー | winternl.h |
ライブラリ | ntdll.lib |
DLL | ntdll.dll |