.\" Copyright (c) 2007 Silicon Graphics, Inc. All Rights Reserved .\" Written by Dave Chinner .\" .\" %%%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 , LDP v2.66 .\" Updated 2008-10-13, Akihiro MOTOKI , LDP v3.11 .\" Updated 2013-05-01, Akihiro MOTOKI .\" Updated 2013-05-07, Akihiro MOTOKI .\" Updated 2013-07-22, Akihiro MOTOKI .\" .TH FALLOCATE 2 2019\-11\-19 Linux "Linux Programmer's Manual" .SH 名前 fallocate \- ファイル空間の操作 .SH 書式 .nf \fB#define _GNU_SOURCE\fP /* feature_test_macros(7) 参照 */ \fB#include \fP .PP \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 .SH 説明 このシステムコールは、移植性のない、Linux 固有のシステムコールである。 移植性が必要な場合は、ファイルに対してディスク空間を確実に確保するために、 POSIX.1 で規定された方法である \fBposix_fallocate\fP(3) を使うこと。 .PP \fBfallocate\fP() を使うと、 \fIfd\fP が参照するファイルに割り当てられたディスク空間を直接操作できる。 操作対象は、 \fIoffset\fP から始まる長さ \fIlen\fP バイトの領域である。 .PP \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) を最適に実装する手段を提供することを目的としているからである。 .PP 呼び出しが成功した場合、 \fIoffset\fP と \fIlen\fP で指定された範囲へのそれ以降の書き込みでは、 ディスクの領域不足での書き込み失敗が起こらないことが保証される。 .PP \fBFALLOC_FL_KEEP_SIZE\fP フラグが \fImode\fP に指定された場合、このシステムコール の動作は似ているが、 \fIoffset\fP+\fIlen\fP がファイルサイズよりも大きい場合で あってもファイルサイズは変更されない点が異なる。この場合のファイルの末尾 よりも後ろの前もって割り当てられた 0 で埋められたブロックは、ファイルへの 追記を最適化したい場合に役に立つ。 .PP If the \fBFALLOC_FL_UNSHARE\fP flag is specified in \fImode\fP, shared file data extents will be made private to the file to guarantee that a subsequent write will not fail due to lack of space. Typically, this will be done by performing a copy\-on\-write operation on all shared data in the file. This flag may not be supported by all filesystems. .PP 割り当てはブロックサイズ単位で行われるため、 \fBfallocate\fP() は指定されたより も大きなディスク領域を割り当てることがある。 .SS ファイル空間の割り当て解除 \fBFALLOC_FL_PUNCH_HOLE\fP フラグ (Linux 2.6.38 以降で利用可能) を \fImode\fP に指定すると、 \fIoffset\fP で始まる \fIlen\fP バイトの領域の空間を解放する (ホールを作成する)。 指定された範囲のうち、 部分的に使用しているファイルシステムブロックは 0 で埋められ、 全体を使用しているファイルシステムブロックはそのファイルから削除される。 呼び出しが成功すると、 これ以降のこの範囲からの読み出しでは 0 を返す。 .PP \fBFALLOC_FL_PUNCH_HOLE\fP フラグは \fBFALLOC_FL_KEEP_SIZE\fP と論理和 (OR) をとって \fImode\fP に指定しなければならない。 つまり、 ファイル末尾の punch off を行った場合でも、 (\fBstat\fP(2) で報告される) ファイルサイズが変化しない。 .PP すべてのファイルシステムで \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 \fBtmpfs\fP(5) (Linux 3.5 以降) .IP * .\" commit 4e56a6411fbce6f859566e17298114c2434391a4 \fBgfs2\fP(5) (Linux 4.16 以降) .SS ファイル空間の一部削除 .\" commit 00f5e61998dd17f5375d9dfc01331f104b83f841 \fBFALLOC_FL_COLLAPSE_RANGE\fP フラグ (Linux 3.15 以降で利用可能) を \fImode\fP に指定すると、 指定したバイト範囲をファイルから削除する。 その際、ホールを残さない。 削除されるバイト範囲は \fIoffset\fP から始まる \fIlen\fP バイトの範囲である。 操作が完了すると、 ファイルの \fIoffset+len\fP の位置から始まる内容が \fIoffset\fP の位置に見えるようになり、 ファイルのサイズは \fIlen\fP バイトだけ小さくなる。 .PP 効率的に動作する実装にするため、ファイルシステムはこの操作の粒度に制限を設けることがある。 通常は \fIoffset\fP と \fIlen\fP はファイルシステムの論理ブロックサイズの倍数でなければならない。 論理ブロックサイズはファイルシステムの種類や設定により様々である。 ファイルシステムにこのような要求条件がある場合、 その要求条件が満たされていなければ、 \fBfallocate\fP はエラー \fBEINVAL\fP で失敗する。 .PP \fIoffset\fP と \fIlen\fP で指定された範囲がファイルの末尾かそれより先まで達している場合、 エラーが返される。 代わりに、ファイルの切り詰めを行う \fBftruncate\fP(2) を使用すること。 .PP \fBFALLOC_FL_COLLAPSE_RANGE\fP と他のフラグを同時に \fImode\fP に指定することはできない。 .PP .\" commit 9eb79482a97152930b113b51dff530aba9e28c8e .\" commit e1d8fb88a64c1f8094b9f6c3b6d2d9e6719c970d Linux 3.15 時点では \fBFALLOC_FL_COLLAPSE_RANGE\fP は ext4 (エクステントベースのファイル) と XFS でサポートされている。 .SS ファイル空間のゼロ埋め .\" commit 409332b65d3ed8cfa7a8030f1e9d52f372219642 \fBFALLOC_FL_ZERO_RANGE\fP フラグ (Linux 3.15 以降で利用可能) を \fImode\fP に指定すると、 \fIoffset\fP で始まる \fIlen\fP バイト範囲の空間をゼロ埋めする。 指定された範囲の中では、ブロックは、そのファイル内のホールが広がる領域にあらかじめ割り当てられたものである。 呼び出しが成功すると、 これ以降のこの範囲からの読み出しでは 0 を返す。 .PP ゼロ埋めは、ファイルシステム内部では、指定された範囲を書き込みを伴わないエクステントに変換する方法をできるだけ使って行われる。 この方法は、指定された範囲について物理的にゼロ埋めしたデータがデバイスに書き込まれるのではないことを意味する (例外は指定された範囲の端の部分的に使用しているブロックである)。 (これ以外で) I/O が必要なのはメタデータの更新だけである。 .PP \fBFALLOC_FL_KEEP_SIZE\fP フラグが \fImode\fP に追加で指定された場合、 このシステムコールの動作は似ているが、 \fIoffset\fP+\fIlen\fP がファイルサイズよりも大きい場合であってもファイルサイズは変更されない点が異なる。 この動作は \fBFALLOC_FL_KEEP_SIZE\fP を指定してスペースを前もって割り当てた場合と同じである。 .PP すべてのファイルシステムで \fBFALLOC_FL_ZERO_RANGE\fP がサポートされているわけではない。 ファイルシステムがこの操作をサポートしていない場合は、 エラーが返る。 この操作は少なくとも以下のファイルシステムでサポートされている。 .IP * 3 .\" commit 376ba313147b4172f3e8cf620b9fb591f3e8cdfa XFS (Linux 3.15 以降) .IP * .\" commit b8a8684502a0fc852afa0056c6bb2a9273f6fcc0 ext4 のエクステントベースのファイル (Linux 3.15 以降) .IP * .\" commit 30175628bf7f521e9ee31ac98fa6d6fe7441a556 SMB3 (Linux 3.17 以降) .IP * .\" commit f27451f229966874a8793995b8e6b74326d125df Btrfs (Linux 4.16 以降) .SS "Increasing file space" .\" commit dd46c787788d5bf5b974729d43e4c405814a4c7d Specifying the \fBFALLOC_FL_INSERT_RANGE\fP flag (available since Linux 4.1) in \fImode\fP increases the file space by inserting a hole within the file size without overwriting any existing data. The hole will start at \fIoffset\fP and continue for \fIlen\fP bytes. When inserting the hole inside file, the contents of the file starting at \fIoffset\fP will be shifted upward (i.e., to a higher file offset) by \fIlen\fP bytes. Inserting a hole inside a file increases the file size by \fIlen\fP bytes. .PP This mode has the same limitations as \fBFALLOC_FL_COLLAPSE_RANGE\fP regarding the granularity of the operation. If the granularity requirements are not met, \fBfallocate\fP() fails with the error \fBEINVAL\fP. If the \fIoffset\fP is equal to or greater than the end of file, an error is returned. For such operations (i.e., inserting a hole at the end of file), \fBftruncate\fP(2) should be used. .PP \fBFALLOC_FL_INSERT_RANGE\fP と他のフラグを同時に \fImode\fP に指定することはできない。 .PP .\" commit a904b1ca5751faf5ece8600e18cd3b674afcca1b .\" commit 331573febb6a224bc50322e3670da326cb7f4cfc .\" f2fs also has support since Linux 4.2 .\" commit f62185d0e283e9d311e3ac1020f159d95f0aab39 \fBFALLOC_FL_INSERT_RANGE\fP requires filesystem support. Filesystems that support this operation include XFS (since Linux 4.1) and ext4 (since Linux 4.2). .SH 返り値 成功の場合、 \fBfallocate\fP() は 0 を返す。 エラーの場合、\-1 を返し、 \fIerrno\fP にエラーを示す値を設定する。 .SH エラー .TP \fBEBADF\fP \fIfd\fP が有効なファイルディスクリプターでないか、 書き込み用としてオープンされていない。 .TP \fBEFBIG\fP \fIoffset + len\fP がファイルサイズの最大値よりも大きい。 .TP \fBEFBIG\fP \fImode\fP is \fBFALLOC_FL_INSERT_RANGE\fP, and the current file size+\fIlen\fP exceeds the maximum file size. .TP \fBEINTR\fP 実行中にシグナルが捕捉された。 \fBsignal\fP(7) 参照。 .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_INSERT_RANGE\fP で、 \fIoffset\fP と \fIlen\fP で指定された範囲がファイルの末尾かそれより先まで達している。 .TP \fBEINVAL\fP \fImode\fP が \fBFALLOC_FL_COLLAPSE_RANGE\fP か \fBFALLOC_FL_INSERT_RANGE\fP だが、 \fIoffset\fP か \fIlen\fP のいずれかがファイルシステムのブロックサイズの倍数ではない。 .TP \fBEINVAL\fP \fImode\fP contains one of \fBFALLOC_FL_COLLAPSE_RANGE\fP or \fBFALLOC_FL_INSERT_RANGE\fP and also other flags; no other flags are permitted with \fBFALLOC_FL_COLLAPSE_RANGE\fP or \fBFALLOC_FL_INSERT_RANGE\fP. .TP \fBEINVAL\fP .\" There was an 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 .\" 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 か \fBFALLOC_FL_INSERT_RANGE\fP だが、 \fIfd\fP が参照しているファイルが通常のファイルではない。 .TP \fBEIO\fP ファイルシステムとの読み書き中に入出力エラーが発生した。 .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) 参照)。 .TP \fBEPERM\fP \fImode\fP に \fBFALLOC_FL_PUNCH_HOLE\fP か \fBFALLOC_FL_COLLAPSE_RANGE\fP か \fBFALLOC_FL_INSERT_RANGE\fP が指定されたが、 \fIfd\fP が参照するファイルに追加のみ (append\-only) の属性が付いている (\fBchattr\fP(1) 参照)。 .TP \fBEPERM\fP 操作が file seal により禁止されている。 \fBfcntl\fP(2) 参照。 .TP \fBESPIPE\fP \fIfd\fP がパイプか FIFO を参照している。 .TP \fBETXTBSY\fP \fImode\fP に \fBFALLOC_FL_COLLAPSE_RANGE\fP か \fBFALLOC_FL_INSERT_RANGE\fP が指定されたが、 \fIfd\fP が参照するファイルは現在実行中である。 .SH バージョン .\" 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 準拠 \fBfallocate\fP() は Linux 固有である。 .SH 関連項目 \fBfallocate\fP(1), \fBftruncate\fP(2), \fBposix_fadvise\fP(3), \fBposix_fallocate\fP(3) .SH この文書について この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は \%https://www.kernel.org/doc/man\-pages/ に書かれている。