release/man2/lseek.2

   1 .\" t
   2 .\" Copyright (c) 1980, 1991 Regents of the University of California.
   3 .\" and Copyright (c) 2011, Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)lseek.2     6.5 (Berkeley) 3/10/91
  35 .\"
  36 .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
  37 .\" Modified 1995-06-10 by Andries Brouwer <aeb@cwi.nl>
  38 .\" Modified 1996-10-31 by Eric S. Raymond <esr@thyrsus.com>
  39 .\" Modified 1998-01-17 by Michael Haardt
  40 .\"   <michael@cantor.informatik.rwth-aachen.de>
  41 .\" Modified 2001-09-24 by Michael Haardt <michael@moria.de>
  42 .\" Modified 2003-08-21 by Andries Brouwer <aeb@cwi.nl>
  43 .\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE
  44 .\"
  45 .\"*******************************************************************
  46 .\"
  47 .\" This file was generated with po4a. Translate the source file.
  48 .\"
  49 .\"*******************************************************************
  50 .TH LSEEK 2 2011\-09\-25 Linux "Linux Programmer's Manual"
  51 .SH 名前
  52 lseek \- ファイルの読み書きオフセットの位置を変える
  53 .SH 書式
  54 \fB#include <sys/types.h>\fP
  55 .br
  56 \fB#include <unistd.h>\fP
  57 .sp
  58 \fBoff_t lseek(int \fP\fIfd\fP\fB, off_t \fP\fIoffset\fP\fB, int \fP\fIwhence\fP\fB);\fP
  59 .SH 説明
  60 \fBlseek\fP()  関数は、ファイルディスクリプタ (descriptor)  \fIfd\fP に対応するオープンされたファイルのオフセットを、
  61 \fIwhence\fP に基づき \fIoffset\fP 引き数の位置へ以下のように変更する:
  62 .TP
  63 \fBSEEK_SET\fP
  64 オフセットは \fIoffset\fP バイトに設定される。
  65 .TP
  66 \fBSEEK_CUR\fP
  67 オフセットは現在位置に \fIoffset\fP バイトを足した位置になる。
  68 .TP
  69 \fBSEEK_END\fP
  70 オフセットはファイルのサイズに \fIoffset\fP バイトを足した位置になる。
  71 .PP
  72 \fBlseek\fP()  関数は、オフセットをファイルの末尾を越えた位置に設定できる (但し、これによりファイルのサイズが変わらない)。
  73 もしデータがこのオフセット位置以降に書き込まれた場合、 間の空隙の部分 ("穴 (hole)") の読み出しがあると、
  74 実際にそこにデータを書き込まれるまでは NULL バイト (\(aq\e0\(aq) の列が返される。
  75 .SS "Seeking file data and holes"
  76 Linux バージョン 3.1 以降では、
  77 \fIwhence\fP に以下の値も指定することができる。
  78 .TP
  79 \fBSEEK_DATA\fP
  80 Adjust the file offset to the next location in the file greater than or
  81 equal to \fIoffset\fP containing data.  If \fIoffset\fP points to data, then the
  82 file offset is set to \fIoffset\fP.
  83 .TP
  84 \fBSEEK_HOLE\fP
  85 Adjust the file offset to the next hole in the file greater than or equal to
  86 \fIoffset\fP.  If \fIoffset\fP points into the middle of a hole, then the file
  87 offset is set to \fIoffset\fP.  If there is no hole past \fIoffset\fP, then the
  88 file offset is adjusted to the end of the file (i.e., there is an implicit
  89 hole at the end of any file).
  90 .PP
  91 In both of the above cases, \fBlseek\fP()  fails if \fIoffset\fP points past the
  92 end of the file.
  93
  94 These operations allow applications to map holes in a sparsely allocated
  95 file.  This can be useful for applications such as file backup tools, which
  96 can save space when creating backups and preserve holes, if they have a
  97 mechanism for discovering holes.
  98
  99 .\" https://lkml.org/lkml/2011/4/22/79
 100 .\" http://lwn.net/Articles/440255/
 101 .\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data
 102 For the purposes of these operations, a hole is a sequence of zeros that
 103 (normally) has not been allocated in the underlying file storage.  However,
 104 a file system is not obliged to report holes, so these operations are not a
 105 guaranteed mechanism for mapping the storage space actually allocated to a
 106 file.  (Furthermore, a sequence of zeros that actually has been written to
 107 the underlying storage may not be reported as a hole.)  In the simplest
 108 implementation, a file system can support the operations by making
 109 \fBSEEK_HOLE\fP always return the offset of the end of the file, and making
 110 \fBSEEK_DATA\fP always return \fIoffset\fP (i.e., even if the location referred to
 111 by \fIoffset\fP is a hole, it can be considered to consist of data that is a
 112 sequence of zeros).
 113 .SH 返り値
 114 成功した場合、 \fBlseek\fP()  は結果のファイル位置をファイルの先頭からのバイト数で返す。 エラーの場合、値 \fI(off_t)\ \-1\fP
 115 が返され、 \fIerrno\fP にエラーが指示される。
 116 .SH エラー
 117 .TP
 118 \fBEBADF\fP
 119 \fIfd\fP がオープンされたファイルディスクリプタでない。
 120 .TP
 121 \fBEINVAL\fP
 122 .\" Some systems may allow negative offsets for character devices
 123 .\" and/or for remote file systems.
 124 \fIwhence\fP が有効な値ではない。または、seek の結果、ファイルオフセットが負に
 125 なってしまうか、 seek 可能なデバイスの末尾を越えてしまう。
 126 .TP
 127 \fBEOVERFLOW\fP
 128 .\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW)
 129 結果のファイルオフセットを \fIoff_t\fP 型で表現することができない。
 130 .TP
 131 \fBESPIPE\fP
 132 \fIfd\fP がパイプ、ソケット、FIFO を参照している。
 133 .TP
 134 \fBENXIO\fP
 135 \fIwhence\fP が \fBSEEK_DATA\fP か \fBSEEK_HOLE\fP で、
 136 現在のファイルオフセットがファイルの末尾を超えた位置である。
 137 .SH 準拠
 138 SVr4, 4.3BSD, POSIX.1\-2001.
 139
 140 .\" FIXME . Review http://austingroupbugs.net/view.php?id=415 in the future
 141 \fBSEEK_DATA\fP and \fBSEEK_HOLE\fP are nonstandard extensions also present in
 142 Solaris, FreeBSD, and DragonFly BSD; they are proposed for inclusion in the
 143 next POSIX revision (Issue 8).
 144 .SH 注意
 145 いくつかのデバイスでは seek ができない。 POSIX はどのデバイスが \fBlseek\fP()  に対応すべきかは規定していない。
 146
 147 .\" Other systems return the number of written characters,
 148 .\" using SEEK_SET to set the counter. (Of written characters.)
 149 Linux では、 tty デバイスに \fBlseek\fP()  を使用すると \fBESPIPE\fP を返す。
 150
 151 古いコードを変換する時は \fIwhence\fP の値を以下のマクロに置き換えること:
 152 .TS
 153 c c
 154 l l.
 155 old     new
 156 0       SEEK_SET
 157 1       SEEK_CUR
 158 2       SEEK_END
 159 L_SET   SEEK_SET
 160 L_INCR  SEEK_CUR
 161 L_XTND  SEEK_END
 162 .TE
 163 .\" .PP
 164 .\" SVr1-3 returns \fIlong\fP instead of \fIoff_t\fP,
 165 .\" (ancient) BSD returns \fIint\fP.
 166 .PP
 167 \fBdup\fP(2)  や \fBfork\fP(2)  で作成されたファイルディスクリプタは、現在のファイル位置ポインタ (current file
 168 position pointer) を共有しているので、 このようなファイルで移動を行うと競合状態を引き起こす可能性がある。
 169 .SH 関連項目
 170 \fBdup\fP(2), \fBfork\fP(2), \fBopen\fP(2), \fBfseek\fP(3), \fBlseek64\fP(3),
 171 \fBposix_fallocate\fP(3)
 172 .SH この文書について
 173 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部
 174 である。プロジェクトの説明とバグ報告に関する情報は
 175 http://www.kernel.org/doc/man\-pages/ に書かれている。