FSEEK(3)

名称
fgetpos, fseek, fseeko, fsetpos, ftell, ftello, rewind - ストリームの位置変更

ライブラリ
libc

書式
<stdio.h> int fseek(FILE *stream, long offset, int whence) long ftell(FILE *stream) void rewind(FILE *stream) int fgetpos(FILE *stream, fpos_t *pos) int fsetpos(FILE *stream, const fpos_t *pos) <sys/types.h> int fseeko(FILE *stream, off_t offset, int whence) off_t ftello(FILE *stream)

解説
fseek() 関数は、 stream が指すストリームのファイル位置インジケータを 設定します。新しい位置はバイト単位で計測され、 whence で指定された位置に offset バイトを足すことで得られます。 whence が SEEK_SET, SEEK_CUR, SEEK_END に設定されている場合、オフセットは、それぞれ、ファイルの最初、 インジケータの現在位置、ファイルの最後からの相対位置になります。 fseek() 関数の呼び出しで 問題が発生しない場合は、ストリームの end-of-file 指示子がクリアされ、 そのストリームに対する ungetc(3) 関数の効果は取り消されます。

ftell() 関数は、 stream が指すストリームのファイル位置インジケータの 現在の値を入手します。

rewind() 関数は、 stream が指すストリームのファイル位置インジケータを ファイルの最初に設定します。これは、 ストリームのエラーインジケータがクリアされること ( clearerr(3) を参照) を除けば、以下と同じ結果になります。

    (void)fseek(stream, 0L, SEEK_SET)

fseeko() 関数は fseek() と同様ですが、 引数には long の代わりに off_t をとります。 同様に ftello() 関数は ftell() と同じですが、 off_t を返します。

fgetpos() 関数と fsetpos() 関数は、( whence を SEEK_SET に設定した ) ftell() や fseek() と同じインタフェースで、ファイルオフセットの現在の値を pos が参照するオブジェクトから設定したり、 pos が参照するオブジェクトに保存したりします。 一部の (UNIX 以外の) システムでは、 “fpos_t” オブジェクトが複合オブジェクトであるかもしれないので、 移植性を保ちながらテキストストリームの位置を 変更するためには、このルーチンに依るしかないこともあります。

戻り値
rewind() 関数は値を返しません。

成功して終了すると、 ftell() および ftello() は現在のオフセットを返します。それ以外の場合は -1 が返され、 グローバル変数 errno が設定されてエラーを示します。

エラー

[EBADF]
    指定された stream が、シークできるストリームではありません。

[EINVAL]
    fseek() の whence 引数が、 SEEK_SET, SEEK_END, SEEK_CUR のどれでもありません。

[EOVERFLOW]
    ftell() を実行した結果のファイルのオフセットが long 型のオブジェクトでは正しく表現できない値となりました。

fgetpos(), fseek(), fseeko(), fsetpos(), ftell(), ftello() 関数が失敗した時には、 ルーチン fflush(3), fstat(2), lseek(2), malloc(3) について示しているエラーが errno に設定されていることもあります。

関連項目
lseek(2)

規格
fgetpos(), fsetpos(), fseek(), ftell(), rewind() 関数は、 isoC に適合しています。

fseeko() と ftello() 関数は、 susv2 に適合しています。