release/man2/fallocate.2

   1 .\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved
   2 .\" Written by Dave Chinner <dgc@sgi.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2_ONELINE)
   5 .\" May be distributed as per GNU General Public License version 2.
   6 .\" %%%LICENSE_END
   7 .\"
   8 .\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE
   9 .\" 2011-09-19: Substantial restructuring of the page
  10 .\"
  11 .\"*******************************************************************
  12 .\"
  13 .\" This file was generated with po4a. Translate the source file.
  14 .\"
  15 .\"*******************************************************************
  16 .\"
  17 .\" Japanese Version Copyright (c) 2007  Akihiro MOTOKI
  18 .\"         all rights reserved.
  19 .\" Translated 2007-10-16, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.66
  20 .\" Updated 2008-10-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.11
  21 .\" Updated 2013-05-01, Akihiro MOTOKI <amotoki@gmail.com>
  22 .\" Updated 2013-05-07, Akihiro MOTOKI <amotoki@gmail.com>
  23 .\" Updated 2013-07-22, Akihiro MOTOKI <amotoki@gmail.com>
  24 .\"
  25 .TH FALLOCATE 2 2014\-04\-17 Linux "Linux Programmer's Manual"
  26 .SH 名前
  27 fallocate \- ファイル空間の操作
  28 .SH 書式
  29 .nf
  30 \fB#define _GNU_SOURCE\fP             /* feature_test_macros(7) 参照 */
  31 \fB#include <fcntl.h>\fP
  32
  33 \fBint fallocate(int \fP\fIfd\fP\fB, int \fP\fImode\fP\fB, off_t \fP\fIoffset\fP\fB, off_t \fP\fIlen\fP\fB);\fP
  34 .fi
  35 .SH 説明
  36 このシステムコールは、移植性のない、Linux 固有のシステムコールである。 移植性が必要な場合は、ファイルに対してディスク空間を確実に確保するために、
  37 POSIX.1 で規定された方法である \fBposix_fallocate\fP(3)  を使うこと。
  38
  39 \fBfallocate\fP()  を使うと、 \fIfd\fP が参照するファイルに割り当てられたディスク空間を直接操作できる。 操作対象は、
  40 \fIoffset\fP から始まる長さ \fIlen\fP バイトの領域である。
  41
  42 \fImode\fP 引き数は、指定された領域に対して実行する操作を指定する。
  43 サポートされている操作の詳細は以下のサブセクションで説明する。
  44 .SS ディスク領域の割り当て
  45 \fBfallocate\fP() のデフォルトの動作 (つまり \fImode\fP が 0 の場合) は、 \fIoffset\fP と \fIlen\fP
  46 で指定された範囲のディスク領域の割り当てを行う。 \fIoffset\fP+\fIlen\fP がファイルサイズよりも大きかった場合、 (\fBstat\fP(2)
  47 で報告される) ファイルサイズが変更される。 \fIoffset\fP と \fIlen\fP で指定される範囲のサブ領域で、
  48 呼び出し前にデータを保持していなかった場合、そのサブ領域は 0 で初期化される。 このデフォルトの動作は、 ライブラリ関数
  49 \fBposix_fallocate\fP(3) の動作と非常に似ている。 これは、 このシステムコールが \fBposix_fallocate\fP(3)
  50 を最適に実装する手段を提供することを目的としているからである。
  51
  52 呼び出しが成功した場合、
  53 \fIoffset\fP と \fIlen\fP で指定された範囲へのそれ以降の書き込みでは、
  54 ディスクの領域不足での書き込み失敗が起こらないことが保証される。
  55
  56 \fBFALLOC_FL_KEEP_SIZE\fP フラグが \fImode\fP に指定された場合、このシステムコール
  57 の動作は似ているが、 \fIoffset\fP+\fIlen\fP がファイルサイズよりも大きい場合で
  58 あってもファイルサイズは変更されない点が異なる。この場合のファイルの末尾
  59 よりも後ろの前もって割り当てられた 0 で埋められたブロックは、ファイルへの
  60 追記を最適化したい場合に役に立つ。
  61 .PP
  62 割り当てはブロックサイズ単位で行われるため、 \fBfallocate\fP() は指定されたより
  63 も大きなディスク領域を割り当てることがある。
  64 .SS ファイル空間の割り当て解除
  65 \fBFALLOC_FL_PUNCH_HOLE\fP フラグ (Linux 2.6.38 以降で利用可能) を \fImode\fP に指定すると、
  66 \fIoffset\fP で始まる \fIlen\fP バイトの領域の空間を解放する (ホールを作成する)。 指定された範囲のうち、
  67 部分的に使用しているファイルシステムブロックは 0 で埋められ、 全体を使用しているファイルシステムブロックはそのファイルから削除される。
  68 呼び出しが成功すると、 これ以降のこの範囲からの読み出しでは 0 を返す。
  69
  70 \fBFALLOC_FL_PUNCH_HOLE\fP フラグは \fBFALLOC_FL_KEEP_SIZE\fP と論理和 (OR) をとって \fImode\fP
  71 に指定しなければならない。 つまり、 ファイル末尾の punch off を行った場合でも、 (\fBstat\fP(2) で報告される)
  72 ファイルサイズが変化しない。
  73
  74 すべてのファイルシステムで \fBFALLOC_FL_PUNCH_HOLE\fP がサポートされているわけではない。
  75 ファイルシステムがこの操作をサポートしていない場合は、 エラーが返る。 この操作は少なくとも以下のファイルシステムでサポートされている。
  76 .IP * 3
  77 XFS (Linux 2.6.38 以降)
  78 .IP *
  79 .\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622
  80 ext4 (Linux 3.0 以降)
  81 .IP *
  82 Btrfs (Linux 3.7 以降)
  83 .IP *
  84 .\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe
  85 tmpfs (Linux 3.5 以降)
  86 .SS "Collapsing file space"
  87 .\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841
  88 Specifying the \fBFALLOC_FL_COLLAPSE_RANGE\fP flag (available since Linux 3.15)
  89 in \fImode\fP removes a byte range from a file, without leaving a hole.  The
  90 byte range to be collapsed starts at \fIoffset\fP and continues for \fIlen\fP
  91 bytes.  At the completion of the operation, the contents of the file
  92 starting at the location \fIoffset+len\fP will be appended at the location
  93 \fIoffset\fP, and the file will be \fIlen\fP bytes smaller.
  94
  95 A filesystem may place limitations on the granularity of the operation, in
  96 order to ensure efficient implementation.  Typically, \fIoffset\fP and \fIlen\fP
  97 must be a multiple of the filesystem logical block size, which varies
  98 according to the filesystem type and configuration.  If a filesystem has
  99 such a requirement, \fBfallocate\fP()  will fail with the error \fBEINVAL\fP if
 100 this requirement is violated.
 101
 102 If the region specified by \fIoffset\fP plus \fIlen\fP reaches or passes the end
 103 of file, an error is returned; instead, use \fBftruncate\fP(2)  to truncate a
 104 file.
 105
 106 No other flags may be specified in \fImode\fP in conjunction with
 107 \fBFALLOC_FL_COLLAPSE_RANGE\fP.
 108
 109 .\" commit 9eb79482a97152930b113b51dff530aba9e28c8e
 110 .\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d
 111 As at Linux 3.15, \fBFALLOC_FL_COLLAPSE_RANGE\fP is supported by ext4 (only for
 112 extent\-based files)  and XFS.
 113 .SH 返り値
 114 成功の場合、 \fBfallocate\fP() は 0 を返す。 エラーの場合、\-1 を返し、 \fIerror\fP にエラーを示す値を設定する。
 115 .SH エラー
 116 .TP
 117 \fBEBADF\fP
 118 \fIfd\fP が有効なファイルディスクリプタでないか、 書き込み用としてオープンされていない。
 119 .TP
 120 \fBEFBIG\fP
 121 \fIoffset + len\fP がファイルサイズの最大値よりも大きい。
 122 .TP
 123 \fBEINTR\fP
 124 実行中にシグナルが捕捉された。
 125 .TP
 126 \fBEINVAL\fP
 127 .\" FIXME (raise a kernel bug) Probably the len==0 case should be
 128 .\" a no-op, rather than an error. That would be consistent with
 129 .\" similar APIs for the len==0 case.
 130 .\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition"
 131 .\" 21 Sep 2012
 132 .\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526
 133 \fIoffset\fP が 0 未満だったか、 \fIlen\fP が 0 以下だった。
 134 .TP
 135 \fBEINVAL\fP
 136 \fImode\fP is \fBFALLOC_FL_COLLAPSE_RANGE\fP and the range specified by \fIoffset\fP
 137 plus \fIlen\fP reaches or passes the end of the file.
 138 .TP
 139 \fBEINVAL\fP
 140 \fImode\fP is \fBFALLOC_FL_COLLAPSE_RANGE\fP, but either \fIoffset\fP or \fIlen\fP is
 141 not a multiple of the filesystem block size.
 142 .TP
 143 \fBEINVAL\fP
 144 mode contains both \fBFALLOC_FL_COLLAPSE_RANGE\fP and other flags; no other
 145 flags are permitted with \fBFALLOC_FL_COLLAPSE_RANGE\fP.
 146 .TP  EINVAL
 147 \fImode\fP
 148 .\" There was a inconsistency in 3.15-rc1, that should be resolved so that all
 149 .\" filesystems use this error for this case. (Tytso says ex4 will change.)
 150 .\" http://thread.gmane.org/gmane.comp.file-systems.xfs.general/60485/focus=5521
 151 .\" From: Michael Kerrisk (man-pages <mtk.manpages@...>
 152 .\" Subject: Re: [PATCH v5 10/10] manpage: update FALLOC_FL_COLLAPSE_RANGE flag in fallocate
 153 .\" Newsgroups: gmane.linux.man, gmane.linux.file-systems
 154 .\" Date: 2014-04-17 13:40:05 GMT
 155 is \fBFALLOC_FL_COLLAPSE_RANGE\fP, but the file referred to by \fIfd\fP is not a
 156 regular file.
 157 .TP
 158 \fBEIO\fP
 159 ファイルシステムとの読み書き中に入出力エラーが発生した。
 160 .TP
 161 \fBENODEV\fP
 162 \fIfd\fP が通常のファイルかディレクトリを参照していない (\fIfd\fP がパイプや FIFO を参照している場合、別のエラーが発生する)。
 163 .TP
 164 \fBENOSPC\fP
 165 \fIfd\fP が参照するファイルを含むデバイスに十分な空き領域がない。
 166 .TP
 167 \fBENOSYS\fP
 168 このカーネルでは \fBfallocate\fP() は実装されていない。
 169 .TP
 170 \fBEOPNOTSUPP\fP
 171 \fIfd\fP が参照するファイルを含むファイルシステムが 指定された操作を
 172 サポートしていない。 \fIfd\fP が参照するファイルを含むファイルシステムが
 173 \fImode\fP をサポートしていない。
 174 .TP
 175 \fBEPERM\fP
 176 The file referred to by \fIfd\fP is marked immutable (see \fBchattr\fP(1)).  Or:
 177 \fImode\fP specifies \fBFALLOC_FL_PUNCH_HOLE\fP or \fBFALLOC_FL_COLLAPSE_RANGE\fP and
 178 the file referred to by \fIfd\fP is marked append\-only (see \fBchattr\fP(1)).
 179 .TP
 180 \fBESPIPE\fP
 181 \fIfd\fP がパイプか FIFO を参照している。
 182 .TP
 183 \fBETXTBSY\fP
 184 \fImode\fP specifies \fBFALLOC_FL_COLLAPSE_RANGE\fP, but the file referred to by
 185 \fIfd\fP is currently being executed.
 186 .SH バージョン
 187 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
 188 \fBfallocate\fP()  はカーネル 2.6.23 以降の Linux で利用可能である。 glibc での対応はバージョン 3.10
 189 以降で行われている。 \fBFALLOC_FL_*\fP が glibc のヘッダファイルで定義されているのは、バージョン 2.18 以降のみである。
 190 .SH 準拠
 191 \fBfallocate\fP()  は Linux 固有である。
 192 .SH 関連項目
 193 \fBfallocate\fP(1), \fBftruncate\fP(2), \fBposix_fadvise\fP(3), \fBposix_fallocate\fP(3)
 194 .SH この文書について
 195 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.65 の一部
 196 である。プロジェクトの説明とバグ報告に関する情報は
 197 http://www.kernel.org/doc/man\-pages/ に書かれている。