ファイルにデータを書き込みます。ファイルポインタの現在位置が、書き込みの開始位置になります。ファイルハンドルがオーバーラップ属性（非同期I/O）指定で作成されていない場合には、書き込みが終了すると、書き込んだバイト数だけファイルポインタの位置が進められます。ファイルハンドルが非同期I/O用に作成されている場合には、アプリケーション側がファイルポインタの位置を変更する必要があります。
BOOL WriteFile( HANDLE hFile, // file handle LPCVOID pBuffer, // buffer DWORD nNumberOfBytesToWrite, // size LPDWORD pNumberOfBytesWritten, // written size LPOVERLAPPED pOverlapped // OVERLAPPED );
KERNEL32.DLL
読み取り先のファイルのハンドルを指定します。このハンドルは、GENERIC_WRITEアクセス権を持っていなければなりません。
非同期書き込み操作では、CreateFile関数でFILE_FLAG_OVERLAPPEDフラグを指定してオープンされたあらゆる種類のハンドル、またはsocket関数やaccept関数から返されたソケットハンドルを、hFileパラメータに指定することができます。
Windows 95/98/Me： 非同期書き込み操作では、CreateFile関数でFILE_FLAG_OVERLAPPEDフラグを指定してオープンされた通信リソース、またはsocket関数やaccept関数から返されたソケットハンドルを、hFileパラメータに指定することができます。メールスロットや名前付きパイプ、ディスクファイルへの非同期書き込み操作を行うことはできません。
書き込むデータが格納されたバッファのアドレスを指定します。
書き込むバイト数を指定します。
このパラメータに0を指定すると、空値の書き込み操作と解釈されます。空値の書き込み操作の動作は、下層のファイルシステムに依存します。ファイルの切り捨てや拡張を行うにはSetEndOfFile関数を使います。
ネットワークを介した名前付きパイプへの書き込み操作では65535バイト以下に制限されます。
実際に書き込まれたバイト数を格納するための変数のアドレスを指定します。WriteFile関数は操作やエラーチェックを行う前に、この値を0に設定します。
pOverlappedパラメータに0 (NULL) を指定した場合は、このパラメータに0 (NULL) を指定することはできません。pOverlappedパラメータに有効なアドレスを指定した場合は、このパラメータに0 (NULL) を指定することができます。非同期書き込み操作の場合は、GetOverlappedResult関数を呼び出すことで書き込まれたバイト数を取得することができます。hFileパラメータがI/O完了ポートに関連付けられている場合は、GetQueuedCompletionStatus関数を呼び出すことで書き込まれたバイト数を取得することができます。
I/O完了ポートを使用していて、pOverlappedパラメータが指すOVERLAPPED構造体に割り当てられたメモリを解放するためにコールバック関数を使用している場合は、このパラメータに0 (NULL) を指定することによって、解放時に起こるメモリ破壊の問題を避けるようにするべきです。このメモリ破壊の問題は、このパラメータに無効なバイト数が返されることによって引き起こされます。
Windows 95/98/Me： このパラメータに0 (NULL) を指定することはできません。
有効なOVERLAPPED構造体のアドレスまたは0 (NULL) を指定します。hFileパラメータのハンドルがFILE_FLAG_OVERLAPPEDフラグを指定してオープンされている場合にはこの構造体が要求されます。
hFileパラメータのハンドルがFILE_FLAG_OVERLAPPEDフラグを指定してオープンされている場合には、このパラメータに0 (NULL) を指定してはいけません。もし0 (NULL) を指定すると、関数が書き込み操作の完了を不正に報告する可能性があります。
hFileパラメータのハンドルがFILE_FLAG_OVERLAPPEDフラグを指定してオープンされていて、このパラメータにOVERLAPPED構造体のアドレスを指定したときは、OVERLAPPED構造体で指定されたオフセットからファイルに非同期的に書き込まれます。制御はすぐに返りますが、書き込みが完了しているとは限りません。この場合、WriteFile関数は0 (FALSE) を返し、GetLastError関数は997 (ERROR_IO_PENDING) を返します。これにより、呼び出しプロセスは書き込み操作が完了するまで処理を続けることができます。書き込みが完了するとOVERLAPPED構造体で指定されたイベントがシグナル状態になります。
hFileパラメータのハンドルがFILE_FLAG_OVERLAPPEDフラグを指定されずにオープンされていて、このパラメータに0 (NULL) を指定したときは、ファイルポインタの現在位置からファイルに同期的に書き込まれます。書き込み操作が完了すると、制御が返ります。
hFileパラメータのハンドルがFILE_FLAG_OVERLAPPEDフラグを指定されずにオープンされていて、このパラメータで有効なOVERLAPPED構造体のアドレスを指定したときは、OVERLAPPED構造体で指定したオフセットからファイルに同期的に書き込まれます。書き込み操作が完了すると、制御が返ります。
Windows 95/98/Me： ファイル、ディスク、パイプ、メールスロットへの操作を行う場合、このパラメータは0 (NULL) でなければなりません。0 (NULL) 以外の値を指定すると呼び出しは失敗します。ただし、シリアルポートおよびパラレルポートの非同期入出力を行うことはできます。
成功すると0以外の値が返ります。
失敗すると0が返ります。拡張エラー情報を取得するには、GetLastError関数を使います。
ほかのプロセスによってロックされている領域に書き込もうとすると、この関数は失敗します。
書き込み操作中の入力バッファにアクセスすると、そのバッファから書き込まれるデータの破壊を引き起こす可能性があります。書き込み操作が終了しない限り、書き込み操作で使用されている入力バッファの書き込み、読み取り、再割り当て、解放を行ってはいけません。
コンソール出力のハンドルを渡すことによって、スクリーンバッファに文字を書き込むことができます。WriteFile関数の正確な動作はコンソールモードによって決定されます。データは現在のカーソル位置に書き込まれます。カーソル位置は書き込み操作後に更新されます。
nNumberOfBytesToWriteパラメータに0を指定すると、空値の書き込み操作が指定されたと解釈され、ファイルの切り捨てや拡張は行われません。ファイルの切り捨てや拡張を行うにはSetEndOfFile関数を使います。
非ブロッキング・バイトモードのパイプハンドルへ書き込む際にバッファ容量が不足している場合、関数は成功しますが、実際に書き込まれたバイト数（pNumberOfBytesWrittenパラメータが指す変数に格納される値）が指定された書き込みバイト数（nNumberOfBytesToWriteパラメータの値）よりも小さくなります。
WriteFile 関数を使用してパイプに書き込む場合、パイプのバッファがいっぱいになると、書き込み操作が完了しない可能性があります。他方のエンドでの読み取り操作によってバッファ容量に余裕ができると、書込み操作が完了します。
匿名読み取りパイプハンドルをクローズした後で、対応する匿名書き込みパイプハンドルを使用して書き込もうとすると、関数は失敗してGetLastError関数が109 (ERROR_BROKEN_PIPE) を返します。
大量の未処理の非同期I/Oが存在する場合には、関数が失敗してGetLastError関数が1784 (ERROR_INVALID_USER_BUFFER) または8 (ERROR_NOT_ENOUGH_MEMORY) を返すことがあります。
未処理の非同期I/Oをすべて中止するには、CancelIO関数を使います。この関数は、指定されたファイルハンドルに対して呼び出しスレッドが発行した操作のみを中止します。中止されるI/O操作はエラー値995 (ERROR_OPERATION_ABORTED) とともに終了します。
フロッピーディスクが入っていないフロッピードライブへ書き込みを試みた場合、ユーザーにもう一度操作を試みるように指示するメッセージボックスが表示されます。メッセージボックスが表示されないようにするには、SetErrorMode関数にSEM_NOOPENFILEERRORBOXを指定します。
Windows 95 以降 / Windows NT 3.1 以降