lseek

LSEEK(2)                    Linux Programmer's Manual                   LSEEK(2)



名前
       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)") の読み出しがあると、
       実際にそこにデータを書き込まれるまでは NULL バイト ('\0') の列が返される。

   Seeking file data and holes
       Linux バージョン 3.1 以降では、 whence に以下の値も指定することができる。

       SEEK_DATA
              Adjust the file offset to the next location in the file greater
              than or equal to offset containing data.  If offset points to
              data, then the file offset is set to offset.

       SEEK_HOLE
              Adjust the file offset to the next hole in the file greater than
              or equal to offset.  If offset points into the middle of a hole,
              then the file offset is set to offset.  If there is no hole past
              offset, then the file offset is adjusted to the end of the file
              (i.e., there is an implicit hole at the end of any file).

       In both of the above cases, lseek()  fails if offset points past the end
       of the file.

       These operations allow applications to map holes in a sparsely allocated
       file.  This can be useful for applications such as file backup tools,
       which can save space when creating backups and preserve holes, if they
       have a mechanism for discovering holes.

       For the purposes of these operations, a hole is a sequence of zeros that
       (normally) has not been allocated in the underlying file storage.
       However, a file system is not obliged to report holes, so these
       operations are not a guaranteed mechanism for mapping the storage space
       actually allocated to a file.  (Furthermore, a sequence of zeros that
       actually has been written to the underlying storage may not be reported
       as a hole.)  In the simplest implementation, a file system can support
       the operations by making SEEK_HOLE always return the offset of the end of
       the file, and making SEEK_DATA always return offset (i.e., even if the
       location referred to by offset is a hole, it can be considered to consist
       of data that is a sequence of zeros).

       The _GNU_SOURCE feature test macro must be defined in order to obtain the
       definitions of SEEK_DATA and SEEK_HOLE from <unistd.h>.

返り値
       成功した場合、 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 and SEEK_HOLE are nonstandard extensions also present in
       Solaris, FreeBSD, and DragonFly BSD; they are proposed for inclusion in
       the next POSIX revision (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.51 の一部
       である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。



Linux                              2013-03-27                           LSEEK(2)