Manpages

名 前

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 の 場 合 ) は 、 offsetlen で 指 定 さ れ た 範 囲 の デ ィ ス ク 領 域 の 割 り 当 て を 行 う 。 offset+len が フ ァ イ ル サ イ ズ よ り も 大 き か っ た 場 合 、 (stat(2) で 報 告 さ れ る ) フ ァ イ ル サ イ ズ が 変 更 さ れ る 。 offsetlen で 指 定 さ れ る 範 囲 の サ ブ 領 域 で 、 呼 び 出 し 前 に デ ー タ を 保 持 し て い な か っ た 場 合 、 そ の サ ブ 領 域 は 0 で 初 期 化 さ れ る 。 こ の デ フ ォ ル ト の 動 作 は 、 ラ イ ブ ラ リ 関 数 posix_fallocate(3) の 動 作 と 非 常 に 似 て い る 。 こ れ は 、 こ の シ ス テ ム コ ー ル が posix_fallocate(3) を 最 適 に 実 装 す る 手 段 を 提 供 す る こ と を 目 的 と し て い る か ら で あ る 。 呼 び 出 し が 成 功 し た 場 合 、 offsetlen で 指 定 さ れ た 範 囲 へ の そ れ 以 降 の 書 き 込 み で は 、 デ ィ ス ク の 領 域 不 足 で の 書 き 込 み 失 敗 が 起 こ ら な い こ と が 保 証 さ れ る 。

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

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

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

Linux 3.15 時 点 で は FALLOC_FL_COLLAPSE_RANGE は ext4 (エ ク ス テ ン ト ベ ー ス の フ ァ イ ル ) と XFS で サ ポ ー ト さ れ て い る 。 フ ァ イ ル 空 間 の ゼ ロ 埋 め
FALLOC_FL_ZERO_RANGE
フ ラ グ (Linux 3.14 以 降 で 利 用 可 能 ) を mode に 指 定 す る と 、 offset で 始 ま る len バ イ ト 範 囲 の 空 間 を ゼ ロ 埋 め す る 。 指 定 さ れ た 範 囲 の 中 で は 、 ブ ロ ッ ク は 、 そ の フ ァ イ ル 内 の ホ ー ル が 広 が る 領 域 に あ ら か じ め 割 り 当 て ら れ た も の で あ る 。 呼 び 出 し が 成 功 す る と 、 こ れ 以 降 の こ の 範 囲 か ら の 読 み 出 し で は 0 を 返 す 。 ゼ ロ 埋 め は 、 フ ァ イ ル シ ス テ ム 内 部 で は 、 指 定 さ れ た 範 囲 を 書 き 込 み を 伴 わ な い エ ク ス テ ン ト に 変 換 す る 方 法 を で き る だ け 使 っ て 行 わ れ る 。 こ の 方 法 は 、 指 定 さ れ た 範 囲 に つ い て 物 理 的 に ゼ ロ 埋 め し た デ ー タ が デ バ イ ス に 書 き 込 ま れ る の で は な い こ と を 意 味 す る (例 外 は 指 定 さ れ た 範 囲 の 端 の 部 分 的 に 使 用 し て い る ブ ロ ッ ク で あ る )。 (こ れ 以 外 で ) I/O が 必 要 な の は メ タ デ ー タ の 更 新 だ け で あ る 。

FALLOC_FL_KEEP_SIZE フ ラ グ が mode に 追 加 で 指 定 さ れ た 場 合 、 こ の シ ス テ ム コ ー ル の 動 作 は 似 て い る が 、 offset+len が フ ァ イ ル サ イ ズ よ り も 大 き い 場 合 で あ っ て も フ ァ イ ル サ イ ズ は 変 更 さ れ な い 点 が 異 な る 。 こ の 動 作 は FALLOC_FL_KEEP_SIZE を 指 定 し て ス ペ ー ス を 前 も っ て 割 り 当 て た 場 合 と 同 じ で あ る 。 す べ て の フ ァ イ ル シ ス テ ム で FALLOC_FL_ZERO_RANGE が サ ポ ー ト さ れ て い る わ け で は な い 。 フ ァ イ ル シ ス テ ム が こ の 操 作 を サ ポ ー ト し て い な い 場 合 は 、 エ ラ ー が 返 る 。 こ の 操 作 は 少 な く と も 以 下 の フ ァ イ ル シ ス テ ム で サ ポ ー ト さ れ て い る 。

*

XFS (Linux 3.14 以 降 )

*

ext4 の エ ク ス テ ン ト ベ ー ス の フ ァ イ ル (Linux 3.14 以 降 )

返 り 値

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

エ ラ ー

EBADF

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

EFBIG

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

EINTR

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

EINVAL

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

EINVAL

modeFALLOC_FL_COLLAPSE_RANGE で 、 offsetlen で 指 定 さ れ た 範 囲 が フ ァ イ ル の 末 尾 か そ れ よ り 先 ま で 達 し て い る 。

EINVAL

modeFALLOC_FL_COLLAPSE_RANGE だ が 、 offsetlen の い ず れ か が フ ァ イ ル シ ス テ ム の ブ ロ ッ ク サ イ ズ の 倍 数 で は な い 。

EINVAL

modeFALLOC_FL_COLLAPSE_RANGE と 他 の フ ラ グ の 両 方 が 指 定 さ れ て い る 。 FALLOC_FL_COLLAPSE_RANGE と 他 の フ ラ グ を 一 緒 に 使 う こ と が で き な い 。

EINVAL

modeFALLOC_FL_COLLAPSE_RANGEFALLOC_FL_ZERO_RANGE だ が 、 fd が 参 照 し て い る フ ァ イ ル が 通 常 の フ ァ イ ル で は な い 。

EIO

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

ENODEV

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

ENOSPC

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

ENOSYS

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

EOPNOTSUPP

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

EPERM

fd が 参 照 す る フ ァ イ ル に 変 更 不 可 (immutable) の 属 性 が 付 い て い る (chattr(1) 参 照 )。

EPERM

modeFALLOC_FL_PUNCH_HOLEFALLOC_FL_COLLAPSE_RANGE が 指 定 さ れ た が 、 fd が 参 照 す る フ ァ イ ル に 追 加 の み (append−only) の 属 性 が 付 い て い る (chattr(1) 参 照 )。

EPERM

操 作 が file seal に よ り 禁 止 さ れ て い る 。 fcntl(2) 参 照 。
ESPIPE

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

ETXTBSY

modeFALLOC_FL_COLLAPSE_RANGE が 指 定 さ れ た が 、 fd が 参 照 す る フ ァ イ ル は 現 在 実 行 中 で あ る 。

バ ー ジ ョ ン

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.79 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は http://www.kernel.org/doc/man−pages/ に 書 か れ て い る 。

COMMENTS