NtSetInformationFile 関数 (ntifs.h)
NtSetInformationFile ルーチンは、ファイル オブジェクトに関するさまざまな種類の情報を変更します。
構文
__kernel_entry NTSYSCALLAPI NTSTATUS NtSetInformationFile(
[in] HANDLE FileHandle,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] PVOID FileInformation,
[in] ULONG Length,
[in] FILE_INFORMATION_CLASS FileInformationClass
);
パラメーター
[in] FileHandle
ファイル オブジェクトへのハンドル。 このハンドルは、 NtCreateFile または NtOpenFile を正常に呼び出すことによって作成 されます。
[out] IoStatusBlock
最終的 な完了 状態と要求された操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 Information メンバーは、ファイルに設定されたバイト数を受け取ります。
[in] FileInformation
ファイルに設定する情報を含むバッファーへのポインター。 このバッファー内の特定の構造体は、 FileInformationClass パラメーターによって決まります。 たとえば、 FileInformationClass パラメーターが FileDispositionInformationEx 定数に設定されている場合、このパラメーターは FILE_DISPOSITION_INFORMATION_EX 構造体へのポインターである必要があります。
[in] Length
FileInformation バッファーのサイズ (バイト単位)。
[in] FileInformationClass
FileInformation が指すバッファーで指定され、ファイルに対して設定される情報の種類。 デバイス ドライバーと中間ドライバーは、次の FILE_INFORMATION_CLASS 値のいずれかを指定できます。
| FILE_INFORMATION_CLASS値 | 返される情報の種類 |
|---|---|
| FileBasicInformation (4) | FILE_BASIC_INFORMATION構造体で提供される情報を変更します。 呼び出し元は、 DesiredAccess パラメーターに FILE_WRITE_ATTRIBUTES フラグを設定してファイルを開いている必要があります。 |
| FileRenameInformation (10) | FILE_RENAME_INFORMATION構造体で指定されている現在のファイル名を変更します。 呼び出し元は、ファイルへの DELETE アクセス権を持っている必要があります。 |
| FileDispositionInformation (13) | ファイルが閉じられたときに削除を要求するか、以前に要求した削除を取り消します。 削除するか取り消すかの選択は、 FILE_DISPOSITION_INFORMATION 構造体で指定されます。 呼び出し元は、 DesiredAccess パラメーターに DELETE フラグを設定してファイルを開いている必要があります。 |
| FilePositionInformation (14) | FILE_POSITION_INFORMATION構造体に格納されている現在のファイル情報を変更します。 |
| FileEndOfFileInformation (20) | FILE_END_OF_FILE_INFORMATION構造体で提供されている現在のファイルの終わり情報を変更します。 この操作では、ファイルを切り捨てたり拡張したりできます。 呼び出し元は、 DesiredAccess パラメーターに FILE_WRITE_DATA フラグを設定してファイルを開いている必要があります。 |
| FileValidDataLengthInformation (39) | ファイルの現在の有効なデータ長を変更します。これは、 FILE_VALID_DATA_LENGTH_INFORMATION 構造体で指定されます。 ファイルは NTFS ボリューム上にあり、呼び出し元は DesiredAccess パラメーターに設定されたFILE_WRITE_DATA フラグを使用してファイルを開いている必要があります。 管理者およびリモート ユーザー以外のユーザーには 、SeManageVolumePrivilege 特権が必要です。 |
| FileShortNameInformation (40) | FILE_NAME_INFORMATION構造体で指定されている現在の短いファイル名を変更します。 ファイルは NTFS ボリューム上にあり、呼び出し元は DesiredAccess パラメーターに DesiredAccess DELETE フラグを設定してファイルを開いている必要があります。 |
| FileIoPriorityHintInformation (43) | ファイル ハンドルの現在の既定の IRP 優先度ヒントを変更します。 新しい値は、 FILE_IO_PRIORITY_HINT_INFORMATION 構造体で指定されます。 この構造体は、8 バイトでアラインされている必要があります。 |
| FileReplaceCompletionInformation (61) | 指定したファイル ハンドルの I/O 完了ポートを変更または削除します。 呼び出し元は、ポート ハンドルと完了キーを指定する FILE_COMPLETION_INFORMATION 構造体へのポインターを提供します。 ポート ハンドルが NULL 以外の場合、このハンドルは、ファイル ハンドルに関連付ける新しい I/O 完了ポートを指定します。 ファイル ハンドルに関連付けられている I/O 完了ポートを削除するには、 構造体のポート ハンドルを NULL に設定します。 ポート ハンドルを取得するために、ユーザー モードの呼び出し元は CreateIoCompletionPort 関数を呼び出すことができます。 |
| FileDispositionInformationEx (64) | ファイルの削除または以前に要求した削除の取り消しを要求します。 削除するか取り消すかの選択、および削除を実行するタイミングと方法の設定は、 FILE_DISPOSITION_INFORMATION_EX 構造で指定されます。 呼び出し元は、 DesiredAccess パラメーターに DELETE フラグを設定してファイルを開いている必要があります。 |
| FileCaseSensitiveInformation (71) | FILE_CASE_SENSITIVE_INFORMATION構造体で提供される情報を変更します。 呼び出し元は、 DesiredAccess パラメーターに FILE_WRITE_ATTRIBUTES フラグを設定してファイルを開いている必要があります。 この値は、バージョン 1803 Windows 10 以降で使用できます。 |
| FileLinkInformation (72) | FILE_LINK_INFORMATION構造で指定されている既存のファイルへのハード リンクを作成します。 すべてのファイル システムがハード リンクをサポートしているわけではありません。たとえば、NTFS は を実行しますが、FAT はしません。 |
| FileCaseSensitiveInformationForceAccessCheck (75) | FILE_CASE_SENSITIVE_INFORMATION構造体で提供される情報を変更します。 呼び出し元は、 DesiredAccess パラメーターに FILE_WRITE_ATTRIBUTES フラグを設定してファイルを開いている必要があります。 これは、ユーザー モードの呼び出し元に適用されるチェックと同様に、IOManager がカーネル モード ドライバーのアクセス チェックを強制的に実行するために使用される FileCaseSensitiveInformation 操作の特別なバージョンです。 この操作は IOManager によってのみ認識され、ファイル システムはそれを受信しないでください。 この値は、バージョン 1803 Windows 10 以降で使用できます。 |
| FileKnownFolderInformation (76) | FILE_KNOWN_FOLDER_INFORMATION構造体。 Windows Server 2022 以降で使用できます。 |
戻り値
NtSetInformationFile は 、STATUS_SUCCESSまたは適切なエラー状態を返します。
注釈
NtSetInformationFile は、 ファイルに関する情報を変更します。 特定のデバイスまたはファイル システムでサポートされていない FILE_XXX_INFORMATION 構造体のメンバーは無視されます。
FileInformationClass をFileDispositionInformation に設定した場合、その後、FileHandle をNtClose に渡すことができますが、他の ZwXxxファイル ルーチンには渡すことができません。 FileDispositionInformation ではファイルが削除対象としてマークされるため、ハンドルを閉じる以外の後続の操作を試行するのはプログラミング エラーです。
FileInformationClass を FilePositionInformation に設定し、NtCreateFile の前の呼び出しで CreateOptions パラメーターに FILE_NO_INTERMEDIATE_BUFFERING フラグが含まれていた場合、FILE_POSITION_INFORMATION構造体の CurrentByteOffset メンバーに対する特定の制限が適用されます。 詳細については、「 NtCreateFile」を参照してください。
FileInformationClass を FileEndOfFileInformation に設定し、FILE_END_OF_FILE_INFORMATIONの EndOfFile メンバーが現在のファイルの末尾マークを超えるオフセットを指定した場合、NtSetInformationFile はファイルを拡張し、拡張子をゼロで埋め込みます。
ファイルの操作の詳細については、「 ドライバーでのファイルの使用」を参照してください。
NtSetInformationFile の呼び出し元は、IRQL = PASSIVE_LEVEL で実行され、特殊なカーネル APCs が有効になっている必要があります。
注意
この関数の呼び出しがユーザー モードで行われる場合は、"ZwSetInformationFile" ではなく"NtSetInformationFile" という名前を使用します。
カーネル モード ドライバーからの呼び出しの場合、Windows ネイティブ システム サービス ルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。 ルーチンの NtXxx**** と ZwXxx**** のバージョン間の関係の詳細については、「ネイティブ システム サービス ルーチンの Nt バージョンと Zw バージョンの使用」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000。 |
| 対象プラットフォーム | ユニバーサル |
| Header | ntifs.h (Wdm.h、Ntddk.h、Ntifs.h を含みます) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (「解説」セクションを参照) |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs、PowerIrpDDis |
関連項目
FILE_IO_PRIORITY_HINT_INFORMATION