WriteFile 関数 (fileapi.h)
指定したファイルまたは入出力 (I/O) デバイスにデータを書き込みます。
この関数は、同期操作と非同期操作の両方を対象に設計されています。 非同期操作専用に設計された同様の関数については、「WriteFileEx
構文
BOOL WriteFile(
[in] HANDLE hFile,
[in] LPCVOID lpBuffer,
[in] DWORD nNumberOfBytesToWrite,
[out, optional] LPDWORD lpNumberOfBytesWritten,
[in, out, optional] LPOVERLAPPED lpOverlapped
);
パラメーター
[in] hFile
ファイルまたは I/O デバイスへのハンドル (ファイル、ファイル ストリーム、物理ディスク、ボリューム、コンソール バッファー、テープ ドライブ、ソケット、通信リソース、mailslot、パイプなど)。
hFile パラメーターは、書き込みアクセス権で作成されている必要があります。 詳細については、「一般的なアクセス権
非同期書き込み操作の場合、
[in] lpBuffer
ファイルまたはデバイスに書き込むデータを格納しているバッファーへのポインター。
このバッファーは、書き込み操作の期間中有効なままである必要があります。 書き込み操作が完了するまで、呼び出し元はこのバッファーを使用しないでください。
[in] nNumberOfBytesToWrite
ファイルまたはデバイスに書き込むバイト数。
値 0 は、null 書き込み操作を指定します。 null 書き込み操作の動作は、基になるファイル システムまたは通信テクノロジによって異なります。
Windows Server 2003 および Windows XP: ネットワーク経由の パイプ書き込み操作のサイズは、書き込みごとに制限されます。 金額はプラットフォームによって異なります。 x86 プラットフォームの場合は 63.97 MB です。 x64 プラットフォームの場合、31.97 MB です。 Itanium の場合は 63.95 MB です。 パイプの詳細については、「解説」セクションを参照してください。
[out, optional] lpNumberOfBytesWritten
同期 hFile パラメーターを使用するときに書き込まれたバイト数を受け取る変数へのポインター。 WriteFile
このパラメーターは、
詳細については、「解説」セクションを参照してください。
[in, out, optional] lpOverlapped
バイト オフセットをサポートする hFile の場合、このパラメーターを使用する場合は、ファイルまたはデバイスへの書き込みを開始するバイト オフセットを指定する必要があります。 このオフセットは、
ファイルの末尾に書き込むには、OVERLAPPED 構造体の Offset メンバーと OffsetHigh メンバーの両方を0xFFFFFFFFとして指定します。 これは、以前に
lpOverlapped と
戻り値
関数が成功した場合、戻り値は 0 以外 (true
関数が失敗した場合、または非同期的に完了している場合、戻り値は 0 (FALSE
備考
WriteFile 関数は、次のいずれかの条件が発生すると返されます。
- 要求されたバイト数が書き込まれます。
- 読み取り操作では、パイプの読み取り側のバッファー領域が解放されます (書き込みがブロックされた場合)。 詳細については、「パイプの」セクションを参照してください。
- 非同期ハンドルが使用されており、書き込みが非同期的に発生しています。
- エラーが発生します。
保留中のすべての非同期 I/O 操作を取り消すには、次のいずれかを使用します。
- CancelIo—この関数は、指定されたファイル ハンドルの呼び出し元スレッドによって発行された操作のみを取り消します。
- CancelIoEx—この関数は、指定されたファイル ハンドルに対してスレッドによって発行されたすべての操作を取り消します。
取り消された I/O 操作は、エラー ERROR_OPERATION_ABORTEDで完了します。
WriteFile 関数は、ERROR_NOT_ENOUGH_QUOTAで失敗する可能性があります。つまり、呼び出し元のプロセスのバッファーをページ ロックできませんでした。 詳細については、「SetProcessWorkingSetSize」を参照してください。
ファイルの一部が別のプロセスによってロックされていて、書き込み操作がロックされた部分と重複している場合、writeFile
ファイルに書き込む場合、書き込みに使用されるすべてのハンドルが閉じられるまで、最後の書き込み時間は完全には更新されません。 そのため、正確な最終書き込み時刻を確保するには、ファイルへの書き込みの直後にファイル ハンドルを閉じます。
書き込み操作でバッファーを使用しているときに出力バッファーにアクセスすると、そのバッファーから書き込まれたデータが破損する可能性があります。 アプリケーションは、書き込み操作が完了するまで、書き込み操作で使用されている出力バッファーへの書き込み、再割り当て、または解放を行う必要はありません。 これは、非同期ファイル ハンドルを使用する場合に特に問題になる可能性があります。 同期と非同期のファイル ハンドルに関する追加情報については、「同期とファイルの位置の の
リモート ファイルのタイムスタンプが正しく更新されない場合があることに注意してください。 一貫性のある結果を得るには、バッファーのない I/O を使用します。
システムは、書き込む 0 バイトを null 書き込み操作を指定すると解釈し、WriteFile
writeFile を使用して、コンソール出力へのハンドル
通信デバイスに書き込む場合、
単一セクター書き込みはアトミックですが、トランザクションを使用しない限り、マルチセクター書き込みはアトミックであるとは限りません (つまり、作成されるハンドルはトランザクション ハンドルです。たとえば、createFileTransacted
マウントされたファイル システムを持つボリュームに直接書き込む場合は、まずボリュームへの排他アクセス権を取得する必要があります。 そうしないと、アプリケーションの書き込みがファイル システムからの他の変更と競合し、ボリュームの内容が不整合な状態のままになる可能性があるため、データの破損やシステムが不安定になるリスクがあります。 これらの問題を回避するために、Windows Vista 以降で次の変更が行われています。
- ボリューム ハンドルへの書き込みは、ボリュームにマウントされたファイル システムがない場合、または次のいずれかの条件が満たされている場合に成功します。
- 書き込むセクターはブート セクターです。
- ファイル システム領域の外部に存在するように書き込まれるセクター。
- FSCTL_LOCK_VOLUME または FSCTL_DISMOUNT_VOLUMEを使用して、ボリュームを明示的にロックまたはマウント解除しました。
- ボリュームに実際のファイル システムがありません。 (つまり、RAW ファイル システムがマウントされています)。
- 次のいずれかの条件に該当する場合、ディスク ハンドルへの書き込みは成功します。
- ボリュームのエクステント内に収まるように書き込まれるセクター。
- マウントされたボリューム内に収まるように書き込まれるセクターが、FSCTL_LOCK_VOLUME または FSCTL_DISMOUNT_VOLUMEを使用してボリュームを明示的にロックまたはマウント解除しました。
- 書き込まれるセクターは、RAW 以外のマウントされたファイル システムがないボリューム内に収まっています。
hFile が FILE_FLAG_OVERLAPPEDで開かれた場合、次の条件が有効になります。
- lpOverlapped パラメーターは、有効で一意の OVERLAPPED 構造体を指している必要があります。そうしないと、関数は書き込み操作が完了したことを誤って報告する可能性があります。
lpNumberOfBytesWritten パラメーターを NULL設定する必要があります。 書き込まれたバイト数を取得するには、GetOverlappedResult 関数を使用します。 hFile パラメーターが I/O 完了ポートに関連付けられている場合は、GetQueuedCompletionStatus 関数を呼び出すことによって書き込まれたバイト数を取得することもできます。
| テクノロジー | サポート |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | はい |
| SMB 3.0 透過的フェールオーバー (TFO) | はい |
| SMB 3.0 とスケールアウト ファイル共有 (SO) | はい |
| クラスター共有ボリューム ファイル システム (CsvFS) | はい |
| 回復性のあるファイル システム (ReFS) | はい |
同期とファイルの位置
FILE_FLAG_OVERLAPPEDhFile を開くと、非同期ファイル ハンドルになります。それ以外の場合は同期です。 前述のように、OVERLAPPED 構造体を使用する規則はそれぞれ若干異なります。- writeFile
書き込み操作が完了する前に返される場合があります。 このシナリオでは、WriteFile は FALSE 返し、 GetLastError 関数はERROR_IO_PENDING を返します。これにより、システムが書き込み操作を完了している間も呼び出しプロセスを続行できます。 lpOverlapped パラメーターは NULLすることはできません。また、次の点を念頭に置いて使用してください。 - OVERLAPPED 構造体で指定されたイベントはシステムによって自動的に設定およびリセットされますが、OVERLAPPED 構造体で指定されたオフセットは自動的に更新されません。
- WriteFile は、I/O 操作の開始時にイベントを非署名状態にリセットします。
- OVERLAPPED 構造体で指定されたイベントは、書き込み操作が完了するとシグナル状態に設定されます。その時点まで、書き込み操作は保留中と見なされます。
- 書き込み操作は、
OVERLAPPED 構造体で指定されたオフセットから開始され、システム レベルの書き込み操作が完了する前に writeFileが返される可能性があるため (書き込み保留中)、オフセットも構造体の他の部分も、イベントが通知されるまでアプリケーションによって変更、解放、または再利用されることはありません 書き込みが完了しました)。
- lpOverlapped が NULL
場合、書き込み操作は現在のファイル位置から開始され、 WriteFile は操作が完了するまで戻らず、WriteFile が戻る前にファイル ポインター更新されます。 - lpOverlapped
NULL されていない場合、書き込み操作は、 が返OVERLAPPED 構造体で指定されたオフセットから開始され、書き込み操作が完了するまで WriteFile戻りません。 システムは、WriteFile 前に、internal フィールドと InternalHigh フィールドとファイル ポインター OVERLAPPED を更新します。
パイプ
匿名パイプが使用されていて、読み取りハンドルが閉じられている場合、アプリケーションが WriteFile 関数を使用してパイプに書き込むときにパイプ バッファーがいっぱいになると、書き込み操作がすぐに完了しない可能性があります。 書き込み操作は、読み取り操作 (ReadFile 関数を使用) によって、パイプに使用できるシステム バッファー領域が増えたときに完了します。
バッファー領域が不足している非ブロッキングバイト モードのパイプ ハンドルに書き込む場合、writeFile
パイプの詳細については、「パイプを
トランザクション操作の
ファイル ハンドルにバインドされたトランザクションがある場合、ファイル書き込みはトランザクションされます。 詳細については、「トランザクション NTFSについて」を参照してください。例
例については、「
#include <windows.h>
#define ROUND_UP_SIZE(Value,Pow2) ((SIZE_T) ((((ULONG)(Value)) + (Pow2) - 1) & (~(((LONG)(Pow2)) - 1))))
#define ROUND_UP_PTR(Ptr,Pow2) ((void *) ((((ULONG_PTR)(Ptr)) + (Pow2) - 1) & (~(((LONG_PTR)(Pow2)) - 1))))
int main()
{
// Sample data
unsigned long bytesPerSector = 65536; // obtained from the GetFreeDiskSpace function.
unsigned long size = 15536; // Buffer size of your data to write.
// Ensure you have one more sector than Size would require.
size_t sizeNeeded = bytesPerSector + ROUND_UP_SIZE(size, bytesPerSector);
// Replace this statement with any allocation routine.
auto buffer = new uint8_t[SizeNeeded];
// Actual alignment happens here.
auto bufferAligned = ROUND_UP_PTR(buffer, bytesPerSector);
// ... Add code using bufferAligned here.
// Replace with corresponding free routine.
delete buffer;
}
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows XP [デスクトップ アプリ |UWP アプリ] |
| サポートされる最小サーバー | Windows Server 2003 [デスクトップ アプリ |UWP アプリ] |
| ターゲット プラットフォーム の |
ウィンドウズ |
| ヘッダー | fileapi.h (Windows.h を含む) |
| ライブラリ | Kernel32.lib |
| DLL | Kernel32.dll |
関連項目
CancelIo を
CancelIoEx を
CancelSynchronousIo の
CreateFile の
CreateFileTransacted の
GetLastError の
GetOverlappedResult の
GetQueuedCompletionStatus を
ReadFile の
SetEndOfFile の
WriteFileEx の