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 の 場 合 ) は 、 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 が サ ポ ー ト さ れ て い る わ け で は な い 。 フ ァ イ ル シ ス テ ム が こ の 操 作 を サ ポ ー ト し て い な い 場 合 は 、 エ ラ ー が 返 る 。 こ の 操 作 は 少 な く と も 以 下 の フ ァ イ ル シ ス テ ム で サ ポ ー ト さ れ て い る 。

フ ァ イ ル 空 間 の 一 部 削 除

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 で サ ポ ー ト さ れ て い る 。 フ ァ イ ル 空 間 の ゼ ロ 埋 め
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 が サ ポ ー ト さ れ て い る わ け で は な い 。 フ ァ イ ル シ ス テ ム が こ の 操 作 を サ ポ ー ト し て い な い 場 合 は 、 エ ラ ー が 返 る 。 こ の 操 作 は 少 な く と も 以 下 の フ ァ イ ル シ ス テ ム で サ ポ ー ト さ れ て い る 。

返 り 値

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

エ ラ ー

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

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