SetFilePointerEx

指定したファイルのファイルポインタを移動する。(SetFilePointerEx)

SetFilePointerEx hFile, liDistanceToMove, lpNewFilePointer, dwMoveMethod

hFile : [intptr] ファイルへのハンドル。ファイルハンドルは GENERIC_READ または GENERIC_WRITE アクセス権で作成されている必要がある。詳細は「ファイルのセキュリティとアクセス権」を参照。
liDistanceToMove : [int64] ファイルポインタを移動するバイト数。正の値はポインタをファイル先頭方向に進め、負の値は後退させる。
lpNewFilePointer : [var] 新しいファイルポインタを受け取る変数へのポインタ。NULL の場合、新しいポインタは返されない。
dwMoveMethod : [int] 

(プラグイン / モジュール : kernel32.dll)

解説

指定したファイルのファイルポインタを移動する。(SetFilePointerEx)

[戻り値]
関数が成功した場合、戻り値は非ゼロである。失敗した場合はゼロである。拡張エラー情報を取得するには GetLastError を呼び出す。

[備考]
この関数が返すファイルポインタはオーバーラップ読み書き操作には使用されない。オーバーラップ操作のオフセットを指定するには
OVERLAPPED 構造体の Offset と OffsetHigh
メンバを使用する。パイプや通信デバイスのような非シーク可能デバイスのハンドルに対して SetFilePointerEx
は使用できない。hFile のファイル種別を判定するには GetFileType
を使用する。マルチスレッドアプリケーションでファイルポインタを設定する際は注意を要する。共有リソースへのアクセスは同期が必要である。例えば、スレッド間でファイルハンドルを共有し、ファイルポインタを更新し、ファイルから読み込むアプリケーションは、この一連の操作をクリティカルセクションオブジェクトやミューテックスオブジェクトで保護する必要がある。詳細は「クリティカルセクションオブジェクト」「ミューテックスオブジェクト」を参照。hFile
ハンドルが FILE_FLAG_NO_BUFFERING
フラグ付きで開かれている場合、アプリケーションはファイルポインタをセクタ整列位置にのみ移動できる。セクタ整列位置とはボリュームのセクタサイズの整数倍となる位置である。ボリュームのセクタサイズは
GetDiskFreeSpace で取得できる。FILE_FLAG_NO_BUFFERING
で開かれたハンドルに対しセクタ整列でない位置となる distance-to-move 値で SetFilePointerEx
を呼ぶと、関数は失敗し GetLastError は ERROR_INVALID_PARAMETER
を返す。詳細は「ファイルバッファリング」を参照。ファイル末尾を超えた位置にファイルポインタを設定することはエラーではない。ファイルサイズは、SetEndOfFile、WriteFile、WriteFileEx
を呼ぶまで増加しない。書き込み操作はファイルサイズをファイルポインタ位置 +
書き込みバッファサイズまで拡大し、間のバイトは未初期化となる。ファイルの長さを知るために SetFilePointerEx
を使用することもできる。dwMoveMethod に FILE_END を指定しオフセット 0
にシークすれば、返るファイルオフセットがファイル長である。しかしこの手法は現在のファイルポインタを保存しないなど予期せぬ副作用を持ちうるため、代わりに
GetFileSizeEx を使用するほうがシンプルで安全である。また、現在のファイルポインタ位置を問い合わせるにも
SetFilePointerEx を使用でき、FILE_CURRENT の移動方法とゼロの距離を指定すればよい。Windows 8 および
Windows Server 2012 では、この関数は以下の技術によってサポートされている。
（以下省略）

情報