SetFilePointer

オープンされているファイルのファイルポインタを移動します。

DWORD SetFilePointer(
    HANDLE hFile,          // ファイルハンドル
    LONG   lDistance,      // 下位オフセット
    PLONG  pDistanceHigh,  // 上位オフセットの変数
    DWORD  dwMoveMethod    // 移動開始点
);

KERNEL32.DLL

引数

hFile

ファイルのハンドルを指定します。このハンドルは、 GENERIC_READ アクセスまたは GENERIC_WRITE アクセスを持っていなければなりません。

lDistance

ファイルポインタを移動させるバイト数を表す符号付き数値の下位32ビットを指定します。

pDistanceHigh パラメータに 0 (NULL) を指定した場合は、新しいファイルポインタの位置のオフセットを表す符号付き32ビット値を指定します。

pDistanceHigh パラメータに有効な変数のアドレスを指定した場合は、新しいファイルポインタの位置のオフセットの下位32ビット値を指定します。 lDistance パラメータで指定された値と pDistanceHigh パラメータで指定される変数に格納されている値で表される符号付き64ビット値が新しいファイルポインタの位置のオフセットになります。

正の値を指定すると順方向に、負の値を指定すると逆方向に移動します。

pDistanceHigh

オフセットの上位32ビット値を格納した変数のアドレスまたは 0 (NULL) を指定します。

変数のアドレスを指定した場合は、関数が成功すると、この変数にファイルポインタの新しい位置の上位32ビット値が格納されます。

このパラメータに変数のアドレスを指定するとオフセット値として最大 (263 - 2) までを指定できますが、0 (NULL) を指定すると最大 (231 - 2) までしか指定できません。

Windows 95/98/Me： このパラメータに有効なアドレスを指定する場合は、その変数には、 0 、0xFFFFFFFF (INVALID_SET_FILE_POINTER) 、または lDistance パラメータの符号拡張のいずれかが格納されていなければなりません。

dwMoveMethod

ファイルポインタ移動の開始点を指定します。次の値のいずれかを指定します。

値 意味
0 (FILE_BEGIN)

ファイルの先頭を移動開始点にします。
1 (FILE_CURRENT)

現在のファイルポインタの位置を移動開始点にします。
2 (FILE_END)

ファイルの終端を移動開始点にします。

戻り値

関数が成功すると、新しいファイルポインタの位置を表す符号なし数値の下位32ビットが返ります。また、 pDistanceHigh パラメータに有効な変数のアドレスを指定した場合には、その変数に上位32ビット値が格納されます。

関数が失敗すると、 0xFFFFFFFF (INVALID_SET_FILE_POINTER) が返ります。拡張エラー情報を取得するには、 GetLastError 関数を使います。

pDistanceHigh パラメータに有効な変数を指定した場合、関数が成功しても戻り値 0xFFFFFFFF (INVALID_SET_FILE_POINTER) が返されてしまうことがあります。これは関数呼出し後の新しいファイルポインタの下位32ビット値が 0xFFFFFFFF になる場合に起こります。この場合、関数が成功していれば GetLastError 関数は 0 (NO_ERROR) を返します。

新しいファイルポインタの位置が負数となる場合は、関数は失敗して、 GetLastError 関数は 131 (ERROR_NEGATIVE_SEEK) を返します。

解説

hFile パラメータで指定されるファイルのファイルポインタは、非同期の読み取りおよび書き込み操作では使用されません。非同期の操作でオフセットを指定するには、 OVERLAPPED 構造体の Offset メンバおよび OffsetHigh メンバを使用します。

ファイルポインタをファイル終端位置の後ろに設定することができます。ファイルサイズは SetEndOfFile 関数、 WriteFile 関数、 WriteFileEx 関数が呼び出されるまでは増加されません。書き込み操作では、ファイルポインタの位置と実際に書き込まれたバッファのサイズの和がファイルサイズになります。このとき、間にある領域は未初期化の状態になります。

SetFilePointer 関数は、ファイルポインタの移動オフセットに 0 を、移動開始点に FILE_CURRENT を指定することで、現在のファイルポインタの位置を取得することができます。

対応情報

Windows 95 以降 / Windows NT 3.1 以降