.\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved
.\" Written by Dave Chinner <dgc@sgi.com>
+.\"
+.\" %%%LICENSE_START(GPLv2_ONELINE)
.\" May be distributed as per GNU General Public License version 2.
+.\" %%%LICENSE_END
+.\"
+.\" 2011-09-19: Added FALLOC_FL_PUNCH_HOLE
+.\" 2011-09-19: Substantial restructuring of the page
+.\"
+.\"*******************************************************************
+.\"
+.\" This file was generated with po4a. Translate the source file.
+.\"
+.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 2007 Akihiro MOTOKI
.\" all rights reserved.
.\" Translated 2007-10-16, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.66
.\" Updated 2008-10-13, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.11
-.\"
-.TH FALLOCATE 2 2010-09-10 "Linux" "Linux Programmer's Manual"
-.\"O .SH NAME
+.\" Updated 2013-05-01, Akihiro MOTOKI <amotoki@gmail.com>
+.\" Updated 2013-05-07, Akihiro MOTOKI <amotoki@gmail.com>
+.\" Updated 2013-07-22, Akihiro MOTOKI <amotoki@gmail.com>
+.\"
+.TH FALLOCATE 2 2014\-07\-08 Linux "Linux Programmer's Manual"
.SH 名前
-.\"O fallocate \- manipulate file space
fallocate \- ファイル空間の操作
-.\"O .SH SYNOPSIS
.SH 書式
.nf
-.\"O .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
-.BR "#define _GNU_SOURCE" " /* feature_test_macros(7) 参照 */"
-.B #include <fcntl.h>
+\fB#define _GNU_SOURCE\fP /* feature_test_macros(7) 参照 */
+\fB#include <fcntl.h>\fP
-.BI "int fallocate(int " fd ", int " mode ", off_t " offset \
-", off_t " len ");"
+\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
.fi
-.\"O .SH DESCRIPTION
.SH 説明
-.\"O This is a nonportable, Linux-specific system call.
-.\"O For the portable, POSIX.1-specified method of ensuring that space
-.\"O is allocated for a file, see
-.\"O .BR posix_fallocate ().
-このシステムコールは、移植性のない、Linux 固有のシステムコールである。
-移植性が必要な場合は、ファイルに対してディスク空間を確実に確保するために、
-POSIX.1 で規定された方法である
-.BR posix_fallocate (3)
-を使うこと。
+このシステムコールは、移植性のない、Linux 固有のシステムコールである。 移植性が必要な場合は、ファイルに対してディスク空間を確実に確保するために、
+POSIX.1 で規定された方法である \fBposix_fallocate\fP(3) を使うこと。
-.\"O .BR fallocate ()
-.\"O allows the caller to directly manipulate the allocated disk space
-.\"O for the file referred to by
-.\"O .I fd
-.\"O for the byte range starting at
-.\"O .I offset
-.\"O and continuing for
-.\"O .I len
-.\"O bytes.
-.BR fallocate ()
-を使うと、
-.I fd
-が参照するファイルに割り当てられたディスク空間を直接操作できる。
-操作対象は、
-.I offset
-から始まる長さ
-.I len
-バイトの領域である。
+\fBfallocate\fP() を使うと、 \fIfd\fP が参照するファイルに割り当てられたディスク空間を直接操作できる。 操作対象は、
+\fIoffset\fP から始まる長さ \fIlen\fP バイトの領域である。
-.\"O The
-.\"O .I mode
-.\"O argument determines the operation to be performed on the given range.
-.\"O Currently only one flag is supported for
-.\"O .IR mode :
-.I mode
-引き数は、指定された領域に対して実行する操作を指定する。
-現在のところ、
-.I mode
-に指定できるフラグは以下の一つだけである。
-.TP
-.B FALLOC_FL_KEEP_SIZE
-.\"O This flag allocates and initializes to zero the disk space
-.\"O within the range specified by
-.\"O .I offset
-.\"O and
-.\"O .IR len .
-.\"O After a successful call, subsequent writes into this range
-.\"O are guaranteed not to fail because of lack of disk space.
-このフラグは、
-.I offset
-と
-.I len
-で指定された領域のディスク空間を割り当て、その空間を 0 で初期化する。
-呼び出しが成功すると、それに続いてこの領域への書き込みが行われるが、
-ディスク空間の不足による書き込み失敗が発生しないことが保証される。
-.\"O Preallocating zeroed blocks beyond the end of the file
-.\"O is useful for optimizing append workloads.
-.\"O Preallocating blocks does not change
-.\"O the file size (as reported by
-.\"O .BR stat (2))
-.\"O even if it is less than
-.\"O .IR offset + len .
-ファイル末尾より後ろの領域について 0 で埋めたブロックを前もって
-割り当てておくことは、追記 (append) の作業負荷を最適化するのに
-有用である。
-ファイルサイズが
-.IR offset + len
-よりも小さい場合であっても、ブロックの前もっての割り当てにより
-.RB ( stat (2)
-が返す) ファイルサイズは変更されることはない。
-.\"
-.\" Note from Amit Arora:
-.\" There were few more flags which were discussed, but none of
-.\" them have been finalized upon. Here are these flags:
-.\" FA_FL_DEALLOC, FA_FL_DEL_DATA, FA_FL_ERR_FREE, FA_FL_NO_MTIME,
-.\" FA_FL_NO_CTIME
-.\" All of the above flags were debated upon and we can not say
-.\" if any/which one of these flags will make it to the later kernels.
-.PP
-.\"O If
-.\"O .B FALLOC_FL_KEEP_SIZE
-.\"O flag is not specified in
-.\"O .IR mode ,
-.\"O the default behavior is almost same as when this flag is specified.
-.\"O The only difference is that on success,
-.\"O the file size will be changed if
-.\"O .I "offset + len"
-.\"O is greater than the file size.
-.\"O This default behavior closely resembles the behavior of the
-.\"O .BR posix_fallocate (3)
-.\"O library function,
-.\"O and is intended as a method of optimally implementing that function.
-.B FALLOC_FL_KEEP_SIZE
-フラグが
-.I mode
-に指定されなかった場合、デフォルトの動作は
-.B FALLOC_FL_KEEP_SIZE
-フラグが指定された場合とほとんど同じとなる。
-唯一の違いは、
-.I "offset + len"
-がファイルサイズよりも大きかった場合、呼び出しが成功すると
-ファイルサイズが変更される点である。
-このデフォルトの動作は、ライブラリ関数
-.BR posix_fallocate (3)
-の動作と非常に似ている。これは
-.BR posix_fallocate (3)
+\fImode\fP 引き数は、指定された領域に対して実行する操作を指定する。
+サポートされている操作の詳細は以下のサブセクションで説明する。
+.SS ディスク領域の割り当て
+\fBfallocate\fP() のデフォルトの動作 (つまり \fImode\fP が 0 の場合) は、 \fIoffset\fP と \fIlen\fP
+で指定された範囲のディスク領域の割り当てを行う。 \fIoffset\fP+\fIlen\fP がファイルサイズよりも大きかった場合、 (\fBstat\fP(2)
+で報告される) ファイルサイズが変更される。 \fIoffset\fP と \fIlen\fP で指定される範囲のサブ領域で、
+呼び出し前にデータを保持していなかった場合、そのサブ領域は 0 で初期化される。 このデフォルトの動作は、 ライブラリ関数
+\fBposix_fallocate\fP(3) の動作と非常に似ている。 これは、 このシステムコールが \fBposix_fallocate\fP(3)
を最適に実装する手段を提供することを目的としているからである。
+
+呼び出しが成功した場合、
+\fIoffset\fP と \fIlen\fP で指定された範囲へのそれ以降の書き込みでは、
+ディスクの領域不足での書き込み失敗が起こらないことが保証される。
+
+\fBFALLOC_FL_KEEP_SIZE\fP フラグが \fImode\fP に指定された場合、このシステムコール
+の動作は似ているが、 \fIoffset\fP+\fIlen\fP がファイルサイズよりも大きい場合で
+あってもファイルサイズは変更されない点が異なる。この場合のファイルの末尾
+よりも後ろの前もって割り当てられた 0 で埋められたブロックは、ファイルへの
+追記を最適化したい場合に役に立つ。
.PP
-.\"O Because allocation is done in block size chunks,
-.\"O .BR fallocate ()
-.\"O may allocate a larger range than that which was specified.
-割り当てはブロックサイズ単位で行われるため、
-.BR fallocate ()
-は指定されたよりも大きな領域を割り当てることがある。
-.\"O .SH RETURN VALUE
+割り当てはブロックサイズ単位で行われるため、 \fBfallocate\fP() は指定されたより
+も大きなディスク領域を割り当てることがある。
+.SS ファイル空間の割り当て解除
+\fBFALLOC_FL_PUNCH_HOLE\fP フラグ (Linux 2.6.38 以降で利用可能) を \fImode\fP に指定すると、
+\fIoffset\fP で始まる \fIlen\fP バイトの領域の空間を解放する (ホールを作成する)。 指定された範囲のうち、
+部分的に使用しているファイルシステムブロックは 0 で埋められ、 全体を使用しているファイルシステムブロックはそのファイルから削除される。
+呼び出しが成功すると、 これ以降のこの範囲からの読み出しでは 0 を返す。
+
+\fBFALLOC_FL_PUNCH_HOLE\fP フラグは \fBFALLOC_FL_KEEP_SIZE\fP と論理和 (OR) をとって \fImode\fP
+に指定しなければならない。 つまり、 ファイル末尾の punch off を行った場合でも、 (\fBstat\fP(2) で報告される)
+ファイルサイズが変化しない。
+
+すべてのファイルシステムで \fBFALLOC_FL_PUNCH_HOLE\fP がサポートされているわけではない。
+ファイルシステムがこの操作をサポートしていない場合は、 エラーが返る。 この操作は少なくとも以下のファイルシステムでサポートされている。
+.IP * 3
+XFS (Linux 2.6.38 以降)
+.IP *
+.\" commit a4bb6b64e39abc0e41ca077725f2a72c868e7622
+ext4 (Linux 3.0 以降)
+.IP *
+Btrfs (Linux 3.7 以降)
+.IP *
+.\" commit 83e4fa9c16e4af7122e31be3eca5d57881d236fe
+tmpfs (Linux 3.5 以降)
+.SS ファイル空間の一部削除
+.\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841
+\fBFALLOC_FL_COLLAPSE_RANGE\fP フラグ (Linux 3.15 以降で利用可能) を \fImode\fP に指定すると、
+指定したバイト範囲をファイルから削除する。 その際、ホールを残さない。 削除されるバイト範囲は \fIoffset\fP から始まる \fIlen\fP
+バイトの範囲である。 操作が完了すると、 ファイルの \fIoffset+len\fP の位置から始まる内容が \fIoffset\fP の位置に見えるようになり、
+ファイルのサイズは \fIlen\fP バイトだけ小さくなる。
+
+効率的に動作する実装にするため、ファイルシステムはこの操作の粒度に制限を設けることがある。 通常は \fIoffset\fP と \fIlen\fP
+はファイルシステムの論理ブロックサイズの倍数でなければならない。 論理ブロックサイズはファイルシステムの種類や設定により様々である。
+ファイルシステムにこのような要求条件がある場合、 その要求条件が満たされていなければ、 \fBfallocate\fP はエラー \fBEINVAL\fP
+で失敗する。
+
+\fIoffset\fP と \fIlen\fP で指定された範囲がファイルの末尾かそれより先まで達している場合、 エラーが返される。
+代わりに、ファイルの切り詰めを行う \fBftruncate\fP(2) を使用すること。
+
+\fBFALLOC_FL_COLLAPSE_RANGE\fP と他のフラグを同時に \fImode\fP に指定することはできない。
+
+.\" commit 9eb79482a97152930b113b51dff530aba9e28c8e
+.\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d
+Linux 3.15 時点では \fBFALLOC_FL_COLLAPSE_RANGE\fP は ext4 (エクステントベースのファイル) と XFS
+でサポートされている。
+.SS ファイル空間のゼロ埋め
+.\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642
+\fBFALLOC_FL_ZERO_RANGE\fP フラグ (Linux 3.14 以降で利用可能) を \fImode\fP に指定すると、 \fIoffset\fP
+で始まる \fIlen\fP バイト範囲の空間をゼロ埋めする。
+指定された範囲の中では、ブロックは、そのファイル内のホールが広がる領域にあらかじめ割り当てられたものである。 呼び出しが成功すると、
+これ以降のこの範囲からの読み出しでは 0 を返す。
+
+ゼロ埋めは、ファイルシステム内部では、指定された範囲を書き込みを伴わないエクステントに変換する方法をできるだけ使って行われる。
+この方法は、指定された範囲について物理的にゼロ埋めしたデータがデバイスに書き込まれるのではないことを意味する
+(例外は指定された範囲の端の部分的に使用しているブロックである)。 (これ以外で) I/O が必要なのはメタデータの更新だけである。
+
+\fBFALLOC_FL_KEEP_SIZE\fP フラグが \fImode\fP に追加で指定された場合、 このシステムコールの動作は似ているが、
+\fIoffset\fP+\fIlen\fP がファイルサイズよりも大きい場合であってもファイルサイズは変更されない点が異なる。 この動作は
+\fBFALLOC_FL_KEEP_SIZE\fP を指定してスペースを前もって割り当てた場合と同じである。
+
+すべてのファイルシステムで \fBFALLOC_FL_ZERO_RANGE\fP がサポートされているわけではない。
+ファイルシステムがこの操作をサポートしていない場合は、 エラーが返る。 この操作は少なくとも以下のファイルシステムでサポートされている。
+.IP * 3
+.\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa
+XFS (Linux 3.14 以降)
+.IP *
+.\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0
+ext4 のエクステントベースのファイル (Linux 3.14 以降)
.SH 返り値
-.\"O .BR fallocate ()
-.\"O returns zero on success, and -1 on failure.
-.BR fallocate ()
-は成功すると 0 を返し、エラーの場合は \-1 を返す。
-.\"O .SH ERRORS
+成功の場合、 \fBfallocate\fP() は 0 を返す。 エラーの場合、\-1 を返し、 \fIerrno\fP にエラーを示す値を設定する。
.SH エラー
-.TP
-.B EBADF
-.\"O .I fd
-.\"O is not a valid file descriptor, or is not opened for writing.
-.I fd
-が有効なファイルディスクリプタでないか、
-書き込み用としてオープンされていない。
-.TP
-.B EFBIG
-.\"O .IR offset + len
-.\"O exceeds the maximum file size.
-.I offset + len
-がファイルサイズの最大値よりも大きい。
-.TP
-.B EINTR
-.\"O A signal was caught during execution.
+.TP
+\fBEBADF\fP
+\fIfd\fP が有効なファイルディスクリプタでないか、 書き込み用としてオープンされていない。
+.TP
+\fBEFBIG\fP
+\fIoffset + len\fP がファイルサイズの最大値よりも大きい。
+.TP
+\fBEINTR\fP
実行中にシグナルが捕捉された。
-.TP
-.B EINVAL
-.\"O .I offset
-.\"O was less than 0, or
-.\"O .I len
-.\"O was less than or equal to 0.
-.I offset
-が 0 未満であるか、
-.I len
-が 0 以下である。
-.TP
-.B EIO
-.\"O An I/O error occurred while reading from or writing to a file system.
+.TP
+\fBEINVAL\fP
+.\" FIXME . (raise a kernel bug) Probably the len==0 case should be
+.\" a no-op, rather than an error. That would be consistent with
+.\" similar APIs for the len==0 case.
+.\" See "Re: [PATCH] fallocate.2: add FALLOC_FL_PUNCH_HOLE flag definition"
+.\" 21 Sep 2012
+.\" http://thread.gmane.org/gmane.linux.file-systems/48331/focus=1193526
+\fIoffset\fP が 0 未満だったか、 \fIlen\fP が 0 以下だった。
+.TP
+\fBEINVAL\fP
+\fImode\fP が \fBFALLOC_FL_COLLAPSE_RANGE\fP で、 \fIoffset\fP と \fIlen\fP
+で指定された範囲がファイルの末尾かそれより先まで達している。
+.TP
+\fBEINVAL\fP
+\fImode\fP が \fBFALLOC_FL_COLLAPSE_RANGE\fP だが、 \fIoffset\fP か \fIlen\fP
+のいずれかがファイルシステムのブロックサイズの倍数ではない。
+.TP
+\fBEINVAL\fP
+\fImode\fP に \fBFALLOC_FL_COLLAPSE_RANGE\fP と他のフラグの両方が指定されている。
+\fBFALLOC_FL_COLLAPSE_RANGE\fP と他のフラグを一緒に使うことができない。
+.TP
+\fBEINVAL\fP
+.\" There was a inconsistency in 3.15-rc1, that should be resolved so that all
+.\" filesystems use this error for this case. (Tytso says ex4 will change.)
+.\" http://thread.gmane.org/gmane.comp.file-systems.xfs.general/60485/focus=5521
+.\" From: Michael Kerrisk (man-pages <mtk.manpages@...>
+.\" Subject: Re: [PATCH v5 10/10] manpage: update FALLOC_FL_COLLAPSE_RANGE flag in fallocate
+.\" Newsgroups: gmane.linux.man, gmane.linux.file-systems
+.\" Date: 2014-04-17 13:40:05 GMT
+\fImode\fP が \fBFALLOC_FL_COLLAPSE_RANGE\fP か \fBFALLOC_FL_ZERO_RANGE\fP だが、 \fIfd\fP
+が参照しているファイルが通常のファイルではない。
+.TP
+\fBEIO\fP
ファイルシステムとの読み書き中に入出力エラーが発生した。
-.TP
-.B ENODEV
-.\"O .I fd
-.\"O does not refer to a regular file or a directory.
-.\"O (If
-.\"O .I fd
-.\"O is a pipe or FIFO, a different error results.)
-.I fd
-が通常のファイルかディレクトリを参照していない
-.RI ( fd
-がパイプや FIFO を参照している場合、別のエラーが発生する)。
-.TP
-.B ENOSPC
-.\"O There is not enough space left on the device containing the file
-.\"O referred to by
-.\"O .IR fd .
-.I fd
-が参照するファイルを含むデバイスに十分な空き領域がない。
-.TP
-.B ENOSYS
-.\"O The file system containing the file referred to by
-.\"O .I fd
-.\"O does not support this operation.
-.I fd
-が参照するファイルを含むファイルシステムが
-指定された操作をサポートしていない。
-.TP
-.B EOPNOTSUPP
-.\"O The
-.\"O .I mode
-.\"O is not supported by the file system containing the file referred to by
-.\"O .IR fd .
-.I fd
-が参照するファイルを含むファイルシステムが
-.I mode
-をサポートしていない。
-.\"O .SH VERSIONS
+.TP
+\fBENODEV\fP
+\fIfd\fP が通常のファイルかディレクトリを参照していない (\fIfd\fP がパイプや FIFO を参照している場合、別のエラーが発生する)。
+.TP
+\fBENOSPC\fP
+\fIfd\fP が参照するファイルを含むデバイスに十分な空き領域がない。
+.TP
+\fBENOSYS\fP
+このカーネルでは \fBfallocate\fP() は実装されていない。
+.TP
+\fBEOPNOTSUPP\fP
+\fIfd\fP が参照するファイルを含むファイルシステムが 指定された操作を
+サポートしていない。 \fIfd\fP が参照するファイルを含むファイルシステムが
+\fImode\fP をサポートしていない。
+.TP
+\fBEPERM\fP
+\fIfd\fP が参照するファイルに変更不可 (immutable) の属性が付いている (\fBchattr\fP(1) 参照)。 \fImode\fP に
+\fBFALLOC_FL_PUNCH_HOLE\fP か \fBFALLOC_FL_COLLAPSE_RANGE\fP が指定されたが、 \fIfd\fP
+が参照するファイルに追加のみ (append\-only) の属性が付いている (\fBchattr\fP(1) 参照)。
+.TP
+\fBESPIPE\fP
+\fIfd\fP がパイプか FIFO を参照している。
+.TP
+\fBETXTBSY\fP
+\fImode\fP に \fBFALLOC_FL_COLLAPSE_RANGE\fP が指定されたが、 \fIfd\fP が参照するファイルは現在実行中である。
.SH バージョン
-.\"O .BR fallocate ()
-.\"O is available on Linux since kernel 2.6.23.
-.\"O Support is provided by glibc since version 2.10.
-.BR fallocate ()
-はカーネル 2.6.23 以降の Linux で利用可能である。
-glibc での対応はバージョン 3.10 以降で行われている。
-.\"O .SH CONFORMING TO
+.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=14964
+\fBfallocate\fP() はカーネル 2.6.23 以降の Linux で利用可能である。 glibc での対応はバージョン 3.10
+以降で行われている。 \fBFALLOC_FL_*\fP が glibc のヘッダファイルで定義されているのは、バージョン 2.18 以降のみである。
.SH 準拠
-.\"O .BR fallocate ()
-.\"O is Linux-specific.
-.BR fallocate ()
-は Linux 固有である。
-.\"O .SH SEE ALSO
+\fBfallocate\fP() は Linux 固有である。
.SH 関連項目
-.BR ftruncate (2),
-.BR posix_fadvise (3),
-.BR posix_fallocate (3)
+\fBfallocate\fP(1), \fBftruncate\fP(2), \fBposix_fadvise\fP(3), \fBposix_fallocate\fP(3)
+.SH この文書について
+この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.76 の一部
+である。プロジェクトの説明とバグ報告に関する情報は
+http://www.kernel.org/doc/man\-pages/ に書かれている。
OSDN Git Service
