書式

#define _GNU_SOURCE /* feature_test_macros(7) 参照 */
#include <fcntl.h>
int fallocate(int fd, int mode, off_t offset, off_t len);

説明

このシステムコールは、移植性のない、Linux 固有のシステムコールである。 移植性が必要な場合は、ファイルに対してディスク空間を確実に確保するために、 POSIX.1 で規定された方法である posix_fallocate(3) を使うこと。

fallocate() を使うと、 fd が参照するファイルに割り当てられたディスク空間を直接操作できる。 操作対象は、 offset から始まる長さ len バイトの領域である。

mode 引き数は、指定された領域に対して実行する操作を指定する。 サポートされている操作の詳細は以下のサブセクションで説明する。

ディスク領域の割り当て

fallocate() のデフォルトの動作 (つまり mode が 0 の場合) は、 offset と len で指定された範囲のディスク領域の割り当てを行う。 offset+len がファイルサイズよりも大きかった場合、 (stat(2) で報告される) ファイルサイズが変更される。 offset と len で指定される範囲のサブ領域で、 呼び出し前にデータを保持していなかった場合、そのサブ領域は 0 で初期化される。 このデフォルトの動作は、 ライブラリ関数 posix_fallocate(3) の動作と非常に似ている。 これは、 このシステムコールが posix_fallocate(3) を最適に実装する手段を提供することを目的としているからである。

呼び出しが成功した場合、 offset と len で指定された範囲へのそれ以降の書き込みでは、 ディスクの領域不足での書き込み失敗が起こらないことが保証される。

FALLOC_FL_KEEP_SIZE フラグが mode に指定された場合、このシステムコール の動作は似ているが、 offset+len がファイルサイズよりも大きい場合で あってもファイルサイズは変更されない点が異なる。この場合のファイルの末尾 よりも後ろの前もって割り当てられた 0 で埋められたブロックは、ファイルへの 追記を最適化したい場合に役に立つ。

割り当てはブロックサイズ単位で行われるため、 fallocate() は指定されたより も大きなディスク領域を割り当てることがある。

ファイル空間の割り当て解除

FALLOC_FL_PUNCH_HOLE フラグ (Linux 2.6.38 以降で利用可能) を mode に指定すると、 offset で始まる len バイトの領域の空間を解放する (ホールを作成する)。 指定された範囲のうち、 部分的に使用しているファイルシステムブロックは 0 で埋められ、 全体を使用しているファイルシステムブロックはそのファイルから削除される。 呼び出しが成功すると、 これ以降のこの範囲からの読み出しでは 0 を返す。

FALLOC_FL_PUNCH_HOLE フラグは FALLOC_FL_KEEP_SIZE と論理和 (OR) をとって mode に指定しなければならない。 つまり、 ファイル末尾の punch off を行った場合でも、 (stat(2) で報告される) ファイルサイズが変化しない。

すべてのファイルシステムで FALLOC_FL_PUNCH_HOLE がサポートされているわけではない。 ファイルシステムがこの操作をサポートしていない場合は、 エラーが返る。 この操作は少なくとも以下のファイルシステムでサポートされている。

*

XFS (Linux 2.6.38 以降)

*

ext4 (Linux 3.0 以降)

*

Btrfs (Linux 3.7 以降)

*

tmpfs (Linux 3.5 以降)

ファイル空間の一部削除

FALLOC_FL_COLLAPSE_RANGE フラグ (Linux 3.15 以降で利用可能) を mode に指定すると、 指定したバイト範囲をファイルから削除する。 その際、ホールを残らない。 削除されるバイト範囲は offset から始まる len バイトの範囲である。 操作が完了すると、 ファイルの offset+len の位置から始まる内容が offset の位置に見えるようになり、 ファイルのサイズは len バイトだけ小さくなる。

効率的に動作する実装にするため、ファイルシステムはこの操作の粒度に制限を設けることがある。 通常は offset と len はファイルシステムの論理ブロックサイズの倍数でなければならない。 論理ブロックサイズはファイルシステムの種類や設定により様々である。 ファイルシステムにこのような要求条件がある場合、 その要求条件が満たされていなければ、 fallocate はエラー EINVAL で失敗する。

offset と len で指定された範囲がファイルの末尾かそれより先まで達している場合、 エラーが返される。 代わりに、ファイルの切り詰めを行う ftruncate(2) を使用すること。

FALLOC_FL_COLLAPSE_RANGE と他のフラグを同時に mode に指定することはできない。

Linux 3.15 時点では FALLOC_FL_COLLAPSE_RANGE は ext4 (エクステントベースのファイル) と XFS でサポートされている。

返り値

成功の場合、 fallocate() は 0 を返す。 エラーの場合、-1 を返し、 error にエラーを示す値を設定する。

バージョン

fallocate() はカーネル 2.6.23 以降の Linux で利用可能である。 glibc での対応はバージョン 3.10 以降で行われている。 FALLOC_FL_* が glibc のヘッダファイルで定義されているのは、バージョン 2.18 以降のみである。

準拠

fallocate() は Linux 固有である。

この文書について

この man ページは Linux man-pages プロジェクトのリリース 3.65 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。