名前

       fallocate - ファイル空間の操作

書式

       #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) で報告される) ファイルサイズが変更される。このデフォルトの動作は、 ライブラ
       リ関数    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 がサポートされているわけではない。  ファイ
       ルシステムがこの操作をサポートしていない場合は、 エラーが返る。

返り値

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

エラー

       EBADF  fd が有効なファイルディスクリプタでないか、 書き込み用としてオープンされていない。

       EFBIG  offset + len がファイルサイズの最大値よりも大きい。

       EINTR  実行中にシグナルが捕捉された。

       EINVAL offset が 0 未満だったか、 len が 0 以下だった。

       EIO    ファイルシステムとの読み書き中に入出力エラーが発生した。

       ENODEV fd が通常のファイルかディレクトリを参照していない (fd がパイプや FIFO  を参照してい
              る場合、別のエラーが発生する)。

       ENOSPC fd が参照するファイルを含むデバイスに十分な空き領域がない。

       ENOSYS このカーネルでは fallocate() は実装されていない。

       EOPNOTSUPP
              fd が参照するファイルを含むファイルシステムが 指定された操作を サポートしていない。
              fd が参照するファイルを含むファイルシステムが mode をサポートしていない。

       EPERM  fd が参照するファイルに変更不可 (immutable) の属性が付いている  (chattr(1)  参照)。
              mode   に  FALLOC_FL_PUNCH_HOLE  が指定されたが、  fd  が参照するファイルに追加のみ
              (append-only) の属性が付いている (chattr(1) 参照)。

       ESPIPE fd がパイプか FIFO を参照している。

バージョン

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

準拠

       fallocate()  は Linux 固有である。

関連項目

       fallocate(1), ftruncate(2), posix_fadvise(3), posix_fallocate(3)

この文書について

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