名前

       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) に入れるよう提案されている。

注意

       いくつかのデバイスでは 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.65 の一部 である。プロジェクト
       の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。