FSEEK(3)

名前
fgetpos, fseek, fsetpos, ftell, rewind - ストリームの位置を変更する #include <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, fpos_t *pos);

説明
fseek 関数は stream によって指定されたストリームにおいて、ファイル位置表示子 (file position indicator) をセットする。新たな位置 (バイト単位) は whence で指定された位置に offset バイトを加えることによって与えられる。 whence が SEEK_SET, SEEK_CUR, SEEK_END のどれかになっている場合は、それぞれファイルの先頭、現在の位置表示子、 ファイルの末尾からのオフセットが取られる。 fseek 関数の呼び出しが成功すると、ストリームの end-of-file 表示子は クリアされ、それまでに ungetc(3) 関数で戻したデータはなかったことになる。

ftell 関数は stream によって指定されたストリームにおける、ファイル位置表示子 の現時点での値を与える。

rewind 関数は stream によって指定されたストリームにおいて、ファイル位置表示子 をファイルの先頭にセットする。この関数は以下と等価である。

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

ただし rewind ではストリームに対するエラー表示子 (error indicator) も同時に クリアされる ( clearerr(3) を見よ)。

fgetpos 関数と fsetpos 関数は、それぞれ ftell と fseek で whence に SEEK_SET を指定した場合と同様の機能を、異なるインターフェースで提供する。 fgetpos はファイルオフセットの現在の値を pos が参照するオブジェクトに保存し、 fsetpos はファイルオフセットを pos に設定する。 UNIX 以外のシステムにおいては、 fpos_t が構造体などの複雑なオブジェクトになっていて、これらのルーチンがテキス トストリームでファイル位置を変更する方法のうち、移植性のある唯一のもの になっている場合もある。

返り値
rewind は返り値を持たない。 fgetpos, fseek, fsetpos は成功すると 0 を返す。 ftell は現在のオフセットを返す。失敗した場合は返り値は -1 となり、グローバ ル変数 errno がエラーに対応した値にセットされる。

エラー

EBADF
    指定した stream がシークできない。

EINVAL
    fseek 関数に対して与えた whence 引数が SEEK_SET, SEEK_END, SEEK_CUR 以外の値であった。

fgetpos, fseek, fsetpos, ftell は、それぞれ fflush(3), fstat(2), lseek(2), malloc(3) などのルーチンを呼び出す際に失敗する可能性がある。この場合は それぞれ対応した errno が設定される。

関連項目
lseek(2)

準拠
fgetpos, fsetpos, fseek, ftell, rewind 関数は ANSI X3.159-1989 (``ANSI C'') に準拠している。