| 標準/拡張機能 | C/C++ | 依存項目 |
|---|---|---|
ISO C |
両方 |
#include <stdio.h>
int fseek(FILE *stream, long int offset, int origin);
#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>
int fseek_unlocked(FILE *stream, long int offset, int origin);fseek() 関数は、stream に関連する現行のファイル位置を、ファイル内の新しい 位置へ変更します。stream での次の操作は、新しい位置で行われます。 更新用にオープンされた stream では、次の操作は読み取り操作または書き込み操作のいずれかです。
正常終了した場合、fseek() 関数は、origin が SEEK_END のときでも、EOF 標識をクリア し、先行する ungetc() または ungetwc() 関数の同じストリームに対する 影響を取り消します。
fseek() 関数または fsetpos() 関数の呼び出しが無効な場合、その 呼び出しはフラッシュとして扱われ、ungetc 文字は廃棄されます。
バイナリー・ストリームの動作: ANSI では、ftell() 関数と fseek() 関数の両方についてバイナリー・ストリームが相対バイト・オフセットを使用すると記述しています。z/OS® XL C/C++ ではこれに該当しますが、可変長レコードを持つレコード指向ファイルの場合は該当しません。このようなタイプのファイルの場合、デフォルトの動作では、SEEK_SET の起点を使用して、ftell() 関数と fseek() 関数についてエンコード・オフセットが使用されます。
エンコード・オフセットでは、ユーザーは、直前の ftell() 関数呼び出しで記録された位置、または位置 0 へのシークだけに制限されます。このようなタイプのファイルに相対バイト・オフセットを使用したい場合は、BYTESEEK fopen() 関数オプションを使用してファイルをオープンするか、またはオープンする前に _EDC_BYTE_SEEK 環境変数を設定することができます。
相対バイト・オフセットで、独自のオフセットを計算できます。オフセットが EOF を超えると、ファイルは NULL で拡張されます。次に新しいデータを書き込む場合に、ファイルが NULL でのみ拡張される、z/OS UNIX ファイルは例外です。これは、POSIX の下で、z/OS UNIX ファイルを使用する場合にも該当します。HFS ファイルは、次に新しいデータを書き込む場合、NULL でのみ拡張されます。
ファイルの先頭より前の位置に変更しようとすると、fseek() 関数は 失敗します。
エンコード・オフセットまたは相対オフセットのどちらが ftell() 関数で 戻されるかに関係なく、SEEK_CUR および SEEK_END を使用するときには、相対オフセットを指定できます。
新しい位置がファイルの先頭より前であれば、fseek() 関数は失敗します。相対オフセットが EOF を超えて位置付けられる場合は、ファイルは NULL で 埋め込まれます。次の新規データの書き込みまで埋め込みが起こらない、z/OS UNIX ファイルを使用する POSIX の場合は例外です。
テキスト・ストリームの動作: テキスト・ストリームの場合、ftell() 関数は、エンコード・オフセットを戻します。起点を SEEK_SET にしてシークすると、位置 0 または直前の ftell() 関数呼び出しで戻された位置へのシークだけに制限されます。
独自の位置を計算しようとしても、その計算はサポートされず、結果的に無効な位置になって fseek() 関数が失敗する場合があります。
SEEK_CUR または SEEK_END を使用している場合、オフセットは相対バイト・オフセットになります。ファイルの開始より前、または EOF を超えてシークしようとすると、結果は 失敗に終わります。
レコード入出力の動作: type=record オープン・モード・パラメーターを使用するレコード入出力のためにオープンされたファイルの 場合、ftell() 関数は、相対レコード番号を戻します。SEEK_SET、SEEK_CUR、および SEEK_END のオリジンの場合は、オフセットは相対レコード 番号になります。
最初のレコードより前、または EOF を超えてシークしようとすると、結果は 失敗に終わります。
ブロック入出力の動作: type=blocked オープン・モード・パラメーターを使用するブロック入出力のためにオープンされたファイルの場合、ftell() 関数は、相対ブロック番号を戻します。SEEK_SET、SEEK_CUR、および SEEK_END のオリジンの場合は、オフセットは相対ブロック番号になります。
最初のブロックより前、または EOF を超えてシークしようとすると、結果は失敗に終わります。
ワイド指向ストリームの動作: 上記の制限のすべてが、すべてのタイプのワイド指向ストリームに適用されます。
マルチボリューム・データ・セットのパフォーマンス: 一般的に fgetpos() 関数および fsetpos() 関数を使用すると、位置変更のパフォーマンスが ftell() 関数および fseek() 関数と比較してよくなります (マルチボリューム・データ・セットで作業する場合)。
MVS データ・セット、VSAM データ・セット、および z/OS UNIX ファイルの大規模ファイル・サポート: AMODE 31 C/C++ アプリケーションの場合、fseek() 関数は符号付き 4 バイトのオフセットを受け入れます。そのため、この関数は、2 GB - 1 を超えるオフセットに直接または相対的に位置付けるのに使用できません。位置変更の制限を回避するために、AMODE 31 C/C++ アプリケーションでは、ヘッダーが組み込まれる前に _LARGE_FILES フィーチャー・テスト・マクロを定義し、fseek() 関数を fseeko() 関数で置き換える必要があります。AMODE 64 C/C++ アプリケーションの場合、大規模ファイルでの fseek() 関数の使用には制限はありません。AMODE 64 バージョンは、符号付き 8 バイトのオフセットを自動的に受け入れます。
正常にポインターを移動できた場合、fseek() 関数は 0 を戻します。
正常に終了しなかった場合、または端末やプリンターのような、シークできないデバイスである場合、fseek() 関数は戻り値をゼロ以外に戻します。
/* This example opens a file myfile.dat for reading.
After performing input operations (not shown), it moves the file
pointer to the beginning of the file.
*/
#include <stdio.h>
int main(void)
{
FILE *stream;
int result;
if (stream = fopen("myfile.dat", "r"))
{ /* successful */
if (fseek(stream, 0L, SEEK_SET)); /* moves pointer to */
/* the beginning of the file */
{ /* if not equal to 0
then error ... */
}
else {
/* fseek() successful */
}
}