名称

lseek — 読み込み/書き込みファイルオフセット位置を変更する

ライブラリ

Standard C Library (libc, -lc)

書式

#include < unistd.h>

off_t
lseek( int fildes, off_t offset, int whence);

解説

lseek() システムコールは、ディレクティブ whence に従ってファイル記述子 fildes のオフセットを引数 offset に移動します。引数 fildes は、オープンファイル記述子でなければなりません。 lseek() システムコールは、次のようにファイル記述子 fildes に対応するファイル位置ポインタを移動します:

• whence が SEEK_SET の場合、オフセットは offset バイトに設定されます。
• whence が SEEK_CUR の場合、オフセットは、現在の位置に offset バイトを加算したものに設定されます。
• whence が SEEK_END の場合、オフセットは、ファイルのサイズに offset バイトを加算したものになります。
• whence が SEEK_HOLE であるなら、オフセットは、供給された offset 以上の次のホールの開始に設定されます。ホールの定義を下記に提供します。
• whence が SEEK_DATA であるなら、オフセットは、供給された offset と等しいか大きい次のホールでない開始に設定されます。

lseek() システムコールによって、ファイルオフセットをファイルの既存のファイルの終り (EOF) を越えるところに設定できます。後にデータがこの点に書き込まれると、それ以後のギャップ内のデータに対する読み込みは (データが実際にギャップ内に書き込まれるまで) データとして 0 を返します。

シークできないデバイスもあります。そのようなデバイスに対応するポインタの値は、未定義になります。

“hole”は、ファイルの連続しているバイトの範囲として定義され、すべての 0 の値がありますが、 SEEK_HOLE で返されたホールは、ファイル中のすべての 0 として表示することが保証されます。ファイルシステムは、 SEEK_HOLE がある 0 の公開された範囲として許可されていますが、必要ではありません。アプリケーションは、0 の範囲のためのそれらの振る舞いを最適化するために SEEK_HOLE を使用することができますが、ファイルのそのようなすべての範囲を見つけるためにそれに依存してはいけません。あらゆるデータ領域の終りでのホールの存在は、簡単なプログラミングのために許可され、ファイルの終りに仮想のホールが存在するのを意味します。アプリケーションは、ファイルシステムが SEEK_HOLE をサポートするかどうか決定するために、 fpathconf( _PC_MIN_HOLE_SIZE) または pathconf( _PC_MIN_HOLE_SIZE) を使用するべきです。 pathconf(2) を参照してください。

ホールに関する情報を提供しないファイルシステムにおいては、ファイルは、全体が 1 つのデータ領域として表現されます。

戻り値

処理が正常に完了すると lseek() は、ファイルの先頭から測定した結果のオフセット位置をバイト単位で返します。そうでない場合は -1 が返され、エラーを示すために errno が設定されます。

エラー

lseek() システムコールは、次の場合に処理を失敗し、ファイル位置ポインタは、変更されません:

[ EBADF]

fildes 引数がオープンファイル記述子ではありません。

[ EINVAL]

whence 引数が正しい値ではないか、計算結果のファイルオフセットがキャラクタ型ではない特殊ファイルに使う負の値となりました。

[ ENXIO]

SEEK_DATA で、供給されたオフセットを通り超える、それ以上のデータ領域がありません。 SEEK_HOLE で、供給されたオフセットを通り超えるそれ以上のホールはありません。

[ EOVERFLOW]

計算結果のファイルオフセットが、 off_t 型のオブジェクトでは正しく表現できない値となりました。

[ ESPIPE]

fildes 引数は、パイプ、ソケット、または FIFO と対応づけられています。

関連項目

dup(2), open(2), pathconf(2)

規格

lseek() システムコールは、 IEEE Std 1003.1-1990 (“POSIX.1”) に適合しています。

歴史

lseek() 関数は、 Version 7 AT&T UNIX で登場しました。

バグ

このドキュメントの whence の使用法は、正しくない英語ですが、歴史的な理由で維持されています。