SetFilePointerEx 関数 (fileapi.h)
指定したファイルのファイル ポインターを移動します。
構文
BOOL SetFilePointerEx(
[in] HANDLE hFile,
[in] LARGE_INTEGER liDistanceToMove,
[out, optional] PLARGE_INTEGER lpNewFilePointer,
[in] DWORD dwMoveMethod
);
パラメーター
[in] hFile
ファイルへのハンドル。 ファイル ハンドルは、 GENERIC_READまたはアクセス 権 GENERIC_WRITE 使用して作成されている必要があります。 詳細については、「 ファイル のセキュリティとアクセス権」を参照してください。
[in] liDistanceToMove
ファイル ポインターを移動するバイト数。 正の値を指定すると、ファイル内でポインターが前方に移動し、負の値を指定すると、ファイル ポインターが後方に移動します。
[out, optional] lpNewFilePointer
新しいファイル ポインターを受け取る変数へのポインター。 このパラメーターが NULL の場合、新しいファイル ポインターは返されません。
[in] dwMoveMethod
ファイル ポインターの移動の開始点。 このパラメーターには、次の値のいずれかを指定できます。
| 値 | 意味 |
|---|---|
|
開始点は 0 またはファイルの先頭です。 このフラグを指定すると、 liDistanceToMove パラメーターは符号なし値として解釈されます。 |
|
開始点は、ファイル ポインターの現在の値です。 |
|
開始点は、現在のファイルの終了位置です。 |
戻り値
関数が成功すると、戻り値は 0 以外になります。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
この関数によって返されるファイル ポインターは、重複する読み取りと書き込みの操作には使用されません。 重複する操作のオフセットを指定するには、OVERLAPPED 構造体の Offset メンバーと OffsetHigh メンバーを使用します。
パイプや通信デバイスなどの見えないデバイスへのハンドルで SetFilePointerEx 関数を使用することはできません。 hFile のファイルの種類を確認するには、GetFileType 関数を使用します。
マルチスレッド アプリケーションでファイル ポインターを設定する場合は注意が必要です。 共有リソースへのアクセスを同期する必要があります。 たとえば、スレッドがファイル ハンドルを共有し、ファイル ポインターを更新し、ファイルから読み取るアプリケーションでは、クリティカル セクション オブジェクトまたはミューテックス オブジェクトを使用してこのシーケンスを保護する必要があります。 これらのオブジェクトの詳細については、「 クリティカル セクション オブジェクト 」および 「ミューテックス オブジェクト」を参照してください。
hFile ハンドルが FILE_FLAG_NO_BUFFERING フラグを設定して開かれた場合、アプリケーションはファイル ポインターをセクターに合わせた位置にのみ移動できます。 セクターに合わせた位置は、ボリュームのセクター サイズの整数倍数である位置です。 アプリケーションは 、GetDiskFreeSpace 関数を呼び出すことによってボリュームのセクター サイズを取得できます。 アプリケーションが距離と移動の値を指定して SetFilePointerEx を呼び出すと、セクターアラインされていない位置と、FILE_FLAG_NO_BUFFERINGで開かれたハンドルが発生すると、関数は失敗し、GetLastError はERROR_INVALID_PARAMETERを返します。 詳細については、「 ファイル バッファリング」を参照してください。
ファイル ポインターをファイルの末尾を超える位置に設定してもエラーではないことに注意してください。 SetEndOfFile、WriteFile、または WriteFileEx 関数を呼び出すまで、ファイルのサイズは増加しません。 書き込み操作では、ファイルポインター位置にファイルのサイズを加えて書き込まれたバッファーのサイズを増やします。これにより、間に存在するバイトがゼロに初期化されます。
SetFilePointerEx を使用して、ファイルの長さを確認できます。 これを行うには、dwMoveMethod に FILE_END を使用し、位置 0 をシークします。 返されるファイル オフセットは、ファイルの長さです。 ただし、この方法では、プログラムがその場所に戻ることができるように、現在のファイル ポインターを保存できないなど、意図しない副作用が発生する可能性があります。 代わりに GetFileSizeEx 関数を使用する方が簡単で安全です。
SetFilePointerEx を使用して、現在のファイル ポインターの位置を照会することもできます。 これを行うには、 FILE_CURRENT の移動方法と 0 の距離を指定します。
Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | はい |
| SMB 3.0 Transparent Failover (TFO) | はい |
| スケールアウト ファイル共有 (SO) を使う SMB 3.0 | はい |
| クラスターの共有ボリューム ファイル システム (CsvFS) | はい |
| Resilient File System (ReFS) | はい |
要件
| サポートされている最小のクライアント | Windows XP [デスクトップ アプリ | UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | fileapi.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |