Provided by: manpages-ja-dev_0.5.0.0.20180315+dfsg-1_all
名前
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/ に書かれている。