名前

       lseek - ファイルの読み書きオフセットの位置を変える

書式

       #include <sys/types.h>
       #include <unistd.h>

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

説明

       lseek()   関数は、ファイルディスクリプター (descriptor)  fd に対応するオープンされたファイ
       ルのオフセットを、 whence に基づき offset 引き数の位置へ以下のように変更する:

       SEEK_SET
              オフセットは offset バイトに設定される。

       SEEK_CUR
              オフセットは現在位置に offset バイトを足した位置になる。

       SEEK_END
              オフセットはファイルのサイズに offset バイトを足した位置になる。

       lseek()  関数は、オフセットをファイルの末尾を越えた位置に設定できる  (但し、これによりファ
       イルのサイズが変わらない)。  もしデータがこのオフセット位置以降に書き込まれた場合、 間の空
       隙の部分 ("穴 (hole)") の読み出しがあると、 実際にそこにデータを書き込まれるまではヌルバイ
       ト ('\0') の列が返される。

   ファイルのデータとホールの探索
       Linux バージョン 3.1 以降では、 whence に以下の値も指定することができる。

       SEEK_DATA
              ファイルオフセットを  offset 以上で次にデータがある位置に設定する。 offset がデータ
              を指している場合には、 ファイルオフセットは offset に設定される。

       SEEK_HOLE
              ファイルオフセットを、 位置が offset 以上の次のホール (hole) に設定する。 offset が
              ホールの内部にある場合は、ファイルシステムは  offset  に設定される。  offset 以降に
              ホールがない場合は、  ファイルオフセットはファイル末尾に設定される  (つまり、  どの
              ファイルの末尾にも暗黙のホールが存在するということだ)。

       上記のどちらの場合も、  offset がファイル末尾よりも先を指している場合には lseek() は失敗す
       る。

       これらの操作を使うことで、 アプリケーションが、 まばら (sparse )  にページが割り当てられた
       ファイルでホールをマップすることができる。  この機能はファイルバックアップツールなどのアプ
       リケーションで有用である。 ホールを見つける仕組みがあれば、 ファイルバックアップツールで、
       バックアップを作成する際に保存領域を節約し、ホールを保持することができる。

       これらの操作の目的としては、  ホールは (通常は) バックエンドのファイルストレージには割り当
       てられていない連続する 0 の列である。 しかし、ファイルシステムにはホールを報告する義務はな
       く、  そのため、 これらの操作は、 ファイルに実際に割り当てられたストレージ領域をマッピング
       する方法としては確実性のある仕組みではない。 (また、バックエンドのストレージに実際に書き込
       まれた連続する   0   の列はホールとして報告されないこともある。)  最も単純な実装としては、
       SEEK_HOLE は常にファイル末尾のオフセットを返すようにし、 SEEK_DATA は常に offset  を返すよ
       うにすることで、  ファイルシステムはこれらの操作をサポートすることができる (SEEK_DATA は常
       に offset を返すというのは、 offset が参照する場所がホールであったとしても、 連続する 0 の
       列のデータで構成されているとみなすということである)。

       <unistd.h>  から SEEK_DATA と SEEK_HOLE の定義を得るには、 機能検査マクロ _GNU_SOURCE を定
       義しなければならない。

       SEEK_HOLE, SEEK_DATA 操作に対応しているのは以下のファイルシステムである。

       *  Btrfs (Linux 3.1 以降)

       *  OCFS (Linux 3.2 以降)

       *  XFS (Linux 3.5 以降)

       *  ext4 (Linux 3.8 以降)

       *  tmpfs (Linux 3.8 以降)

返り値

       成功した場合、 lseek()  は結果のファイル位置をファイルの先頭からのバイト数で返す。  エラー
       の場合、値 (off_t) -1 が返され、 errno にエラーが指示される。

エラー

       EBADF  fd がオープンされたファイルディスクリプターでない。

       EINVAL whence が有効な値ではない。または、seek の結果、ファイルオフセットが負に なってしま
              うか、 seek 可能なデバイスの末尾を越えてしまう。

       EOVERFLOW
              結果のファイルオフセットを off_t 型で表現することができない。

       ESPIPE fd がパイプ、ソケット、FIFO を参照している。

       ENXIO  whence が SEEK_DATA か SEEK_HOLE で、  現在のファイルオフセットがファイルの末尾を超
              えた位置である。

準拠

       SVr4, 4.3BSD, POSIX.1-2001.

       SEEK_DATA  と  SEEK_HOLE は非標準の拡張で、 Solaris, FreeBSD, DragonFly BSD にも存在する。
       これらは POSIX の次の版 (Issue 8) に入れるよう提案されている。

注意

       ファイルディスクリプター、オープンファイル記述、ファイルの関係の説明については open(2)  を
       参照。

       いくつかのデバイスでは  seek ができない。 POSIX はどのデバイスが lseek()  に対応すべきかは
       規定していない。

       Linux では、端末 (terminal) デバイスに lseek() を使用すると ESPIPE が返る。

       古いコードを変換する時は whence の値を以下のマクロに置き換えること:

        old       new
       0        SEEK_SET
       1        SEEK_CUR
       2        SEEK_END
       L_SET    SEEK_SET
       L_INCR   SEEK_CUR
       L_XTND   SEEK_END

       dup(2)  や  fork(2)   で作成されたファイルディスクリプターは、現在のファイル位置ポインター
       (current  file position pointer) を共有しているので、 このようなファイルで移動を行うと競合
       状態を引き起こす可能性がある。

関連項目

       dup(2), fork(2), open(2), fseek(3), lseek64(3), posix_fallocate(3)

この文書について

       この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部  である。プロジェクト
       の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。