SetFilePointerEx

https://msdn.microsoft.com/ja-jp/library/cc428944.aspx https://msdn.microsoft.com/ja-jp/library/ms682530.aspx https://msdn.microsoft.com/ja-jp/library/ms684266.aspx https://msdn.microsoft.com/ja-jp/library/cc428944.aspx

開いたファイルのファイルポインタを移動します。

BOOL SetFilePointerEx(
  HANDLE hFile,
  LARGE_INTEGER liDistanceToMove,
  PLARGE_INTEGER lpNewFilePointer,
  DWORD dwMoveMethod
);

パラメータ

hFile
ファイルポインタを移動するファイルのハンドルを指定します。ファイルハンドルは、ファイルへの GENERIC_READ アクセスまたは GENERIC_WRITE アクセスで作成されていなければなりません。
liDistanceToMove
ファイルポインタを移動するバイト数を指定します。正の値を指定すると、ポインタはファイルの前方に移動します。負の値を指定すると、後方に移動します。
lpNewFilePointer
新しいファイルポインタを受け取る変数へのポインタを指定します。NULL を指定すると、新しいファイルポインタは返されません。
dwMoveMethod
ファイルポインタの移動を開始する位置を指定します。次のいずれかの値を指定します。
意味
FILE_BEGIN0、またはファイルの先頭が開始点になります。このフラグを指定すると、liDistanceToMove パラメータは符号のない値として解釈されます。
FILE_CURRENT現在のファイルポインタの値が開始点になります。
FILE_END現在ファイルの終端の位置が開始点になります。

戻り値

関数が成功すると、0 以外の値が返ります。
関数が失敗すると、0 が返ります。拡張エラー情報を取得するには、 関数を使います。

解説

SetFilePointerEx 関数にパイプや通信デバイスのような、シークを行わない装置のハンドルを指定することはできません。hFile のファイルタイプを判断するには、GetFileType 関数を使います。
マルチスレッドアプリケーションでファイルポインタを設定する場合は注意が必要です。共有リソースへのアクセスは同期させなければなりません。たとえば、複数のスレッドがファイルハンドルの共有、ファイルポインタの更新、ファイルの読み取りなどを実行するアプリケーションでは、クリティカルセクションオブジェクトやミューテックスオブジェクトを使ってこの順序を守る必要があります。これらのオブジェクトの詳細については、「」と「」を参照してください。

FILE_FLAG_NO_BUFFERING フラグをセットして hFile ハンドルを開いた場合、アプリケーションはファイルポインタをセクタの境界整列位置にだけ移動することができます。セクタの境界整列位置は、ボリュームのセクタサイズの倍数( 整数)です。ボリュームのセクタサイズを取得するには、GetDiskFreeSpaceEx 関数を呼び出します。移動距離だけを表してセクタの境界整列を指示しない値と FILE_FLAG_NO_BUFFERING を使って開いたハンドルを指定して SetFilePointerEx 関数を呼び出すと、関数が失敗し、 関数から ERROR_INVALID_PARAMETER が返ります。

ファイルポインタをファイルの終端よりも後ろに設定してもエラーにならないので注意してください。SetEndOfFileWriteFile、または WriteFileEx 関数を呼び出すまでファイルサイズは増えません。書き込み操作を実行すると、ファイルサイズは、書き込まれたバッファのサイズをファイルポインタの位置に足したサイズに増加します。このとき、間にあるバイトは初期化されません。

SetFilePointerEx 関数では、ファイルの長さを確認することができます。この場合、dwMoveMethod パラメータに FILE_END を指定し、位置 0 を検索します。その結果返されるファイルオフセットがファイルの長さになります。ただし、この操作を実行すると、予期しない結果が発生することがあります。たとえば、プログラムを現在のファイルポインタの場所に戻すために必要な、現在のファイルポインタの保存に失敗することがあります。そのため、ファイルの長さを確認するには GetFileSizeEx 関数を使った方が簡単で安全です。
また、SetFilePointerEx 関数は、現在のファイルポインタの位置を照会することもできます。この場合、移動方法として FILE_CURRENT を、移動距離として 0 を指定します。

対応情報

Windows NT/2000:Windows 2000 を使います。
Windows 95/98:対応していません。
Windows CE:対応していません。
ヘッダー:winbase.h で宣言されています。
インポートライブラリ:kernel32.lib を使います。

参照

GetDiskFreeSpaceExGetFileSizeExGetFileTypeSetEndOfFileWriteFileWriteFileEx

表示: