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 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\" %%%LICENSE_END
  35 .\"
  36 .\"     @(#)lseek.2     6.5 (Berkeley) 3/10/91
  37 .\"
  38 .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
  39 .\" Modified 1995-06-10 by Andries Brouwer <aeb@cwi.nl>
  40 .\" Modified 1996-10-31 by Eric S. Raymond <esr@thyrsus.com>
  41 .\" Modified 1998-01-17 by Michael Haardt
  42 .\"   <michael@cantor.informatik.rwth-aachen.de>
  43 .\" Modified 2001-09-24 by Michael Haardt <michael@moria.de>
  44 .\" Modified 2003-08-21 by Andries Brouwer <aeb@cwi.nl>
  45 .\" 2011-09-18, mtk, Added SEEK_DATA + SEEK_HOLE
  46 .\"
  47 .\"*******************************************************************
  48 .\"
  49 .\" This file was generated with po4a. Translate the source file.
  50 .\"
  51 .\"*******************************************************************
  52 .\"
  53 .\" Japanese Version Copyright (c) 1997-1998 HANATAKA Shinya
  54 .\"         all rights reserved.
  55 .\" Translated 1997-02-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  56 .\" Modified 1998-05-11, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  57 .\" Updated 2001-12-14, Kentaro Shirakata <argrath@ub32.org>
  58 .\" Updated 2003-09-08, Kentaro Shirakata <argrath@ub32.org>
  59 .\" Updated 2005-02-24, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  60 .\" Updated 2006-03-05, Akihiro MOTOKI, catch up to LDP v2.25
  61 .\" Updated 2013-05-01, Akihiro MOTOKI <amotoki@gmail.com>
  62 .\" Updated 2013-05-07, Akihiro MOTOKI <amotoki@gmail.com>
  63 .\"
  64 .TH LSEEK 2 2014\-01\-22 Linux "Linux Programmer's Manual"
  65 .SH 名前
  66 lseek \- ファイルの読み書きオフセットの位置を変える
  67 .SH 書式
  68 \fB#include <sys/types.h>\fP
  69 .br
  70 \fB#include <unistd.h>\fP
  71 .sp
  72 \fBoff_t lseek(int \fP\fIfd\fP\fB, off_t \fP\fIoffset\fP\fB, int \fP\fIwhence\fP\fB);\fP
  73 .SH 説明
  74 \fBlseek\fP()  関数は、ファイルディスクリプタ (descriptor)  \fIfd\fP に対応するオープンされたファイルのオフセットを、
  75 \fIwhence\fP に基づき \fIoffset\fP 引き数の位置へ以下のように変更する:
  76 .TP
  77 \fBSEEK_SET\fP
  78 オフセットは \fIoffset\fP バイトに設定される。
  79 .TP
  80 \fBSEEK_CUR\fP
  81 オフセットは現在位置に \fIoffset\fP バイトを足した位置になる。
  82 .TP
  83 \fBSEEK_END\fP
  84 オフセットはファイルのサイズに \fIoffset\fP バイトを足した位置になる。
  85 .PP
  86 \fBlseek\fP()  関数は、オフセットをファイルの末尾を越えた位置に設定できる (但し、これによりファイルのサイズが変わらない)。
  87 もしデータがこのオフセット位置以降に書き込まれた場合、 間の空隙の部分 ("穴 (hole)") の読み出しがあると、
  88 実際にそこにデータを書き込まれるまではヌルバイト (\(aq\e0\(aq) の列が返される。
  89 .SS ファイルのデータとホールの探索
  90 Linux バージョン 3.1 以降では、 \fIwhence\fP に以下の値も指定することができる。
  91 .TP
  92 \fBSEEK_DATA\fP
  93 ファイルオフセットを \fIoffset\fP 以上で次にデータがある位置に設定する。 \fIoffset\fP がデータを指している場合には、
  94 ファイルオフセットは \fIoffset\fP に設定される。
  95 .TP
  96 \fBSEEK_HOLE\fP
  97 ファイルオフセットを、 位置が \fIoffset\fP 以上の次のホール (hole) に設定する。 \fIoffset\fP
  98 がホールの内部にある場合は、ファイルシステムは \fIoffset\fP に設定される。 \fIoffset\fP 以降にホールがない場合は、
  99 ファイルオフセットはファイル末尾に設定される (つまり、 どのファイルの末尾にも暗黙のホールが存在するということだ)。
 100 .PP
 101 上記のどちらの場合も、 \fIoffset\fP がファイル末尾よりも先を指している場合には \fBlseek\fP() は失敗する。
 102
 103 これらの操作を使うことで、 アプリケーションが、 まばら (sparse ) にページが割り当てられたファイルでホールをマップすることができる。
 104 この機能はファイルバックアップツールなどのアプリケーションで有用である。 ホールを見つける仕組みがあれば、 ファイルバックアップツールで、
 105 バックアップを作成する際に保存領域を節約し、ホールを保持することができる。
 106
 107 .\" https://lkml.org/lkml/2011/4/22/79
 108 .\" http://lwn.net/Articles/440255/
 109 .\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data
 110 これらの操作の目的としては、 ホールは (通常は) バックエンドのファイルストレージには割り当てられていない連続する 0 の列である。
 111 しかし、ファイルシステムにはホールを報告する義務はなく、 そのため、 これらの操作は、
 112 ファイルに実際に割り当てられたストレージ領域をマッピングする方法としては確実性のある仕組みではない。
 113 (また、バックエンドのストレージに実際に書き込まれた連続する 0 の列はホールとして報告されないこともある。) 最も単純な実装としては、
 114 \fBSEEK_HOLE\fP は常にファイル末尾のオフセットを返すようにし、 \fBSEEK_DATA\fP は常に \fIoffset\fP を返すようにすることで、
 115 ファイルシステムはこれらの操作をサポートすることができる (\fBSEEK_DATA\fP は常に \fIoffset\fP を返すというのは、 \fIoffset\fP
 116 が参照する場所がホールであったとしても、 連続する 0 の列のデータで構成されているとみなすということである)。
 117
 118 \fI<unistd.h>\fP から \fBSEEK_DATA\fP と \fBSEEK_HOLE\fP の定義を得るには、 機能検査マクロ
 119 \fB_GNU_SOURCE\fP を定義しなければならない。
 120
 121 \fBSEEK_HOLE\fP, \fBSEEK_DATA\fP 操作に対応しているのは以下のファイルシステムである。
 122 .IP * 3
 123 Btrfs (Linux 3.1 以降)
 124 .IP * 3
 125 .\" commit 93862d5e1ab875664c6cc95254fc365028a48bb1
 126 OCFS (Linux 3.2 以降)
 127 .IP *
 128 XFS (Linux 3.5 以降)
 129 .IP *
 130 ext4 (Linux 3.8 以降)
 131 .IP *
 132 tmpfs (Linux 3.8 以降)
 133 .SH 返り値
 134 成功した場合、 \fBlseek\fP()  は結果のファイル位置をファイルの先頭からのバイト数で返す。 エラーの場合、値 \fI(off_t)\ \-1\fP
 135 が返され、 \fIerrno\fP にエラーが指示される。
 136 .SH エラー
 137 .TP
 138 \fBEBADF\fP
 139 \fIfd\fP がオープンされたファイルディスクリプタでない。
 140 .TP
 141 \fBEINVAL\fP
 142 .\" Some systems may allow negative offsets for character devices
 143 .\" and/or for remote filesystems.
 144 \fIwhence\fP が有効な値ではない。または、seek の結果、ファイルオフセットが負に
 145 なってしまうか、 seek 可能なデバイスの末尾を越えてしまう。
 146 .TP
 147 \fBEOVERFLOW\fP
 148 .\" HP-UX 11 says EINVAL for this case (but POSIX.1 says EOVERFLOW)
 149 結果のファイルオフセットを \fIoff_t\fP 型で表現することができない。
 150 .TP
 151 \fBESPIPE\fP
 152 \fIfd\fP がパイプ、ソケット、FIFO を参照している。
 153 .TP
 154 \fBENXIO\fP
 155 \fIwhence\fP が \fBSEEK_DATA\fP か \fBSEEK_HOLE\fP で、
 156 現在のファイルオフセットがファイルの末尾を超えた位置である。
 157 .SH 準拠
 158 SVr4, 4.3BSD, POSIX.1\-2001.
 159
 160 .\" FIXME . Review http://austingroupbugs.net/view.php?id=415 in the future
 161 \fBSEEK_DATA\fP と \fBSEEK_HOLE\fP は非標準の拡張で、 Solaris, FreeBSD, DragonFly BSD
 162 にも存在する。 これらは POSIX の次の版 (Issue 8) に入れるよう提案されている。
 163 .SH 注意
 164 いくつかのデバイスでは seek ができない。 POSIX はどのデバイスが \fBlseek\fP()  に対応すべきかは規定していない。
 165
 166 .\" Other systems return the number of written characters,
 167 .\" using SEEK_SET to set the counter. (Of written characters.)
 168 Linux では、端末 (terminal) デバイスに \fBlseek\fP() を使用すると \fBESPIPE\fP が返る。
 169
 170 古いコードを変換する時は \fIwhence\fP の値を以下のマクロに置き換えること:
 171 .TS
 172 c c
 173 l l.
 174 old     new
 175 0       SEEK_SET
 176 1       SEEK_CUR
 177 2       SEEK_END
 178 L_SET   SEEK_SET
 179 L_INCR  SEEK_CUR
 180 L_XTND  SEEK_END
 181 .TE
 182 .\" .PP
 183 .\" SVr1-3 returns \fIlong\fP instead of \fIoff_t\fP,
 184 .\" (ancient) BSD returns \fIint\fP.
 185 .PP
 186 \fBdup\fP(2)  や \fBfork\fP(2)  で作成されたファイルディスクリプタは、現在のファイル位置ポインタ (current file
 187 position pointer) を共有しているので、 このようなファイルで移動を行うと競合状態を引き起こす可能性がある。
 188 .SH 関連項目
 189 \fBdup\fP(2), \fBfork\fP(2), \fBopen\fP(2), \fBfseek\fP(3), \fBlseek64\fP(3),
 190 \fBposix_fallocate\fP(3)
 191 .SH この文書について
 192 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.65 の一部
 193 である。プロジェクトの説明とバグ報告に関する情報は
 194 http://www.kernel.org/doc/man\-pages/ に書かれている。