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).
返り値¶
成功した場合、
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 では、 tty デバイスに
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.40 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man-pages/
に書かれている。