fseek(3S)

構文

#include <stdio.h>

int fseek(FILE *stream, long int offset, int whence);

int fseeko(FILE *stream, off_t offset, int whence);

void rewind(FILE *stream);

long int ftell(FILE *stream);

off_t ftello(FILE *stream);

説明

fseek() は stream のファイル位置指標をセットします。 ファイル位置は先頭からのバイト数で計ったものです。 新しい位置は、 offset を whence で指定された位置に足すと得られます。 指定された位置とは、ファイルの先頭 SEEK_SET、 現在位置 SEEK_CUR、 あるいはファイルの最後 SEEK_END です。

fseeko() は、POSIX 標準ではない API であり、 コンパイルオプション _LARGEFILE_SOURCE で指定します。 この関数は、 パラメータ offset が long int ではなく off_t であること以外は fseek() と同じです。 その他のすべての関数動作、戻り値、およびエラーは、 POSIX の fseek() と同じです。

ftell() 以外で、 stream 上で一番最後に行われた操作が fflush() である場合、ファイル記述子のファイルオフセットは、 fseek() によって指定された位置を反映するように調整されます。

rewind(stream) は fseek (stream, 0L, SEEK_SET) と同じですが、戻り値はありません。

fseek() および rewind() は ungetc(3S) の効果を取り消します。

fseek() あるいは rewind() の実行後、アップデート用にオープンされているファイルへの操作は、入力、出力どちらも可能です。 fseek() は stream の EOF 指標をクリアします。 rewind() は clearerr() ferror(3S) 参照) を暗黙に呼び出します。

ftell() は、 stream に対応するファイルの、先頭に相対する現在のバイトのオフセットを返します。

ftello() は、POSIX 標準ではない API であり、 コンパイルオプション _LARGEFILE_SOURCE で指定します。 この関数は、 long int ではなく off_t を返すこと以外は ftell() と同じです。 その他のすべての関数動作、戻り値、およびエラーは、 POSIX の ftell() と同じです。

戻り値

fseek() および fseek_unlocked() は正常終了すると ０ を、失敗すると -1 を返し、 エラーを示す値を errno にセットします。

ftell() および ftell_unlocked() は、ストリームのファイル位置指標の現在の値をファイルの先頭からのバイト数で返します。 ftell() および ftell_unlocked() は失敗すると -1 を返し、 エラーを示す値を errno に設定します。

rewind() および rewind_unlocked() は値を返しません。 アプリケーションでエラーを見つけたい場合、 rewind() または rewind_unlocked() を呼ぶ前に errno をクリアし、呼び出し後、 errno が ０ 以外であれば、エラーの起きたことがわかります。

エラー

fseek(), fseeko(), fseek_unlocked(), ftell(), ftello(), ftell_unlocked(), rewind() および rewind_unlocked() は、 stream がバッファーされていないとき、およびバッファーされていて、しかも表示する必要のあるデータがあるとき、または次の条件のときに失敗します。

fseek() および fseek_unlocked() はまた以下の条件で失敗します。

中から呼び出される write() および lseek() 関数がこれ以外の値を errno にセットすることがあります write(2) および lseek(2) 参照)。

警告

HP-UX システムでは ftell() が返すオフセットは、バイト数で計られていて、そこから相対位置をシークしてもさしつかえありません。しかし、 HP-UX でないシステムに移行する場合、 ftell() または ftell_unlocked() で得たオフセットなしで、直接 fseek() に使用してください。 ある種のオペレーティングシステムではオフセットをバイト数で返さないので、計算が意味を持たないからです。

fseek(), fseek_unlocked(), rewind() および rewind_unlocked() は追加モードでオープンされたストリームに対しては何も行いません fopen(3S) 参照)。

fseek_unlocked(), ftell_unlocked() および rewind_unlocked() インタフェースは廃止され、現在では既存の DCE アプリケーションとの互換性を保つためにだけサポートされています。新しいマルチスレッドアプリケーションでは、 fseek(), ftell() および rewind() を使用してください。

参照

lseek(2), write(2), ferror(3S), flockfile(3S), fopen(3S), fgetpos(3S), fgetpos64(3S), ungetc(3S), thread_safety(5)

標準準拠

fseek(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

ftell(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

rewind(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C