名称

fgetpos, fseek, fseeko, fsetpos, ftell, ftello, rewind — ストリームを位置付けし直す

ライブラリ

Standard C Library (libc, -lc)

書式

#include < stdio.h>

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

long
ftell( FILE *stream);

void
rewind( FILE *stream);

int
fgetpos( FILE * restrict stream, fpos_t * restrict pos);

int
fsetpos( FILE *stream, const fpos_t *pos);

#include < 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() 関数の呼び出しが成功すれば、ストリームのファイル終了指示子がクリアされ、同じストリームの ungetc(3) と ungetwc(3) 関数の効果は取り消します。

ftell() 関数は、 stream で指されるストリームのファイル位置指示子の現在の値を取得します。

rewind() 関数は、 stream で指されるストリームのファイル位置指示子をファイルの先頭に設定します。これは、ストリームのエラー指示子がクリアされること ( clearerr(3) を参照) を除いて、次と同じとなります。

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

rewind() は値を返さないので、エラーを検出したいアプリケーションは errno をクリアし、それから rewind() を呼び出し、 errno が 0 でなければ、エラーが生じたと仮定すべきです。

fseeko() 関数は long の代わりに off_t 引数をとることを除いて、 fseek() と同様です。同様に ftello() 関数は off_t を返すことを除いて、 ftell() と同様です。

fgetpos() と fsetpos() 関数はファイルの現在の位置を検索して設定するための代わりのインタフェースで、現在の位置が pos によって指されたタイプ fpos_t の不透明なオブジェクトに格納されることを除いて ftell() と fseek() と同様です。 (訳注: "不透明な (opaque)"はサイズや形がわからないこと。) これらの関数は long int で表すことができるものより大きいオフセットにシークする移植性のある方法を提供します。また、それらは、状態依存のコード化でマルチバイト文字を含んだファイルを容易にシークするための追加状態情報を fpos_t オブジェクト中に格納するかもしれません。 fpos_t は伝統的に整数のタイプですが、アプリケーションは、それがそうであると仮定できません。特に、それらはこのタイプのオブジェクトで演算を実行してはいけません。

ストリームがワイド文字のストリーム ( fwide(3) 参照) であるなら、 offset と whence の組み合わせで指定される位置は、マルチバイトシーケンスの最初のバイトを含まなければなりません。

戻り値

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

The fgetpos(), fseek(), fseeko(), and fsetpos() functions return the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

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

エラー

[ EBADF]

stream 引数は、シークできるストリームではありません。

[ EINVAL]

whence 引数が無効であるか、または結果として生じるファイル位置指示子 (インジケータ) は負の数に設定されるでしょう。

[ EOVERFLOW]

結果として生じるファイルオフセットは fseeko() と ftello() のためのタイプ off_t か fseek() と ftell() のための long のオブジェクトで正しく表現できない値となりました。

[ ESPIPE]

基本的なストリームのファイル記述子はパイプか FIFO に関連しているか、またはファイル位置指示子 (インジケータ) の値は不特定です ( ungetc(3) を参照)。

関数 fgetpos(), fseek(), fseeko(), fsetpos(), ftell(), ftello() と rewind() が失敗した時には、ルーチン fflush(3), fstat(2), lseek(2) と malloc(3) で明記されたエラーのいずれかが errno に設定されます。

関連項目

lseek(2), clearerr(3), fwide(3), ungetc(3), ungetwc(3)

規格

fgetpos(), fsetpos(), fseek(), ftell(), rewind() 関数は、 ISO/IEC 9899:1990 (“ISO C90”) に適合しています。

fseeko() と ftello() 関数は、 IEEE Std 1003.1-2001 (“POSIX.1”) に適合しています。