| 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 にエラーが指示される。
エラー¶
準拠¶
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/ に書かれている。
| 2013-03-27 | Linux |