Manpages

名 前

rename, renameat, renameat2 − フ ァ イ ル の 名 前 や 位 置 を 変 更 す る

書 式

#include <stdio.h>

int rename(const char *oldpath, const char *newpath);

#include <fcntl.h> /* AT_* 定 数 の 定 義 */
#include <stdio.h>

int renameat(int olddirfd, const char *oldpath,
int newdirfd, const char *newpath);

int renameat2(int olddirfd, const char *oldpath,
int newdirfd, const char *newpath, unsigned int flags);

glibc 向 け の 機 能 検 査 マ ク ロ の 要 件 (feature_test_macros(7) 参 照 ):

renameat():

glibc 2.10 以 降 :

_XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L

glibc 2.10 よ り 前 :

_ATFILE_SOURCE

説 明

rename() は フ ァ イ ル の 名 前 を 変 更 し 、 必 要 な ら ば デ ィ レ ク ト リ 間 の 移 動 を 行 な う 。 そ の フ ァ イ ル に 対 す る (link(2) を 使 用 し て 作 ら れ た ) 他 の ハ ー ド リ ン ク (hard link) に は 影 響 は な い 。 オ ー プ ン 済 の oldpath に 対 す る フ ァ イ ル デ ィ ス ク リ プ タ ー に も 影 響 は な い 。

newpath が 既 に 存 在 す る 場 合 、 そ れ は 不 可 分 操 作 で (atomically) 置 き 換 え ら れ る (た だ し 、 い く つ か の 条 件 が あ る ; 以 下 の 「 エ ラ ー 」 の セ ク シ ョ ン を 参 照 )。 そ の た め 、 newpath に ア ク セ ス し よ う と し て い る 他 の プ ロ セ ス が フ ァ イ ル を 見 失 う こ と は な い (訳 註 : 常 に ア ク セ ス 可 能 で あ る )。

oldpath と newpath が ど ち ら も 既 存 の ハ ー ド リ ン ク で 、 同 じ フ ァ イ ル を 参 照 し て い る 場 合 、 rename() は 何 も 行 わ ず 、 ス テ ー タ ス と し て 成 功 を 返 す 。

newpath が 存 在 し 、 何 ら か の 理 由 で 操 作 が 失 敗 し た 場 合 、 rename() は newpath の 実 体 を 元 の ま ま 残 す こ と を 保 証 す る 。

oldpath に は デ ィ レ ク ト リ を 指 定 す る こ と も で き る 。 こ の 場 合 、 newpath は 存 在 し な い か 、 空 の デ ィ レ ク ト リ で な け れ ば な ら な い 。 一 方 で 、 上 書 き を 行 な う 場 合 は 、 rename が 行 な わ れ る フ ァ イ ル を oldpath と newpath の 両 方 で 参 照 で き る 瞬 間 が お そ ら く 存 在 す る 。

oldpath が シ ン ボ リ ッ ク リ ン ク (symbolic link) を 参 照 し て い る 場 合 は 、 リ ン ク の 名 前 が 変 更 さ れ る 。 ま た 、 newpath が シ ン ボ リ ッ ク リ ン ク を 参 照 し て い る 場 合 は 、 リ ン ク が 上 書 き さ れ る 。

renameat()
renameat() シ ス テ ム コ ー ル は rename() と 全 く 同 様 に 動 作 す る が 、 以 下 で 説 明 す る 点 が 異 な る 。

oldpath で 指 定 さ れ た パ ス 名 が 相 対 パ ス の 場 合 、 こ の パ ス 名 は フ ァ イ ル デ ィ ス ク リ プ タ ー olddirfd が 参 照 す る デ ィ レ ク ト リ に 対 す る 相 対 パ ス と 解 釈 さ れ る (rename(2) に 相 対 パ ス 名 を 渡 し た 場 合 の よ う に 、 呼 び 出 し た プ ロ セ ス の カ レ ン ト ワ ー キ ン グ デ ィ レ ク ト リ に 対 す る 相 対 パ ス で は な い )。

oldpath で 指 定 さ れ た パ ス 名 が 相 対 パ ス で 、 olddirfd が 特 別 な 値 AT_FDCWD の 場 合 、 (rename(2) と 同 様 に ) oldpath は 呼 び 出 し た プ ロ セ ス の カ レ ン ト ワ ー キ ン グ デ ィ レ ク ト リ に 対 す る 相 対 パ ス と 解 釈 さ れ る 。

oldpath で 指 定 さ れ た パ ス 名 が 絶 対 パ ス の 場 合 、 olddirfd は 無 視 さ れ る 。

newpath の 解 釈 は oldpath と 同 じ で あ る 。 相 対 パ ス の パ ス 名 が フ ァ イ ル デ ィ ス ク リ プ タ ー newdirfd が 参 照 す る デ ィ レ ク ト リ と 解 釈 さ れ る 点 だ け が 異 な る 。

renameat() の 必 要 性 に つ い て の 説 明 に つ い て は openat(2) を 参 照 。

renameat2()
renameat2() に は 追 加 の flags 引 き 数 が あ る 。 flags 引 き 数 が 0 の renameat2() の 呼 び 出 し は renameat() と 等 価 で あ る 。

flags 引 き 数 は 、 以 下 の フ ラ グ の 0 個 以 上 の ビ ッ ト マ ス ク で あ る 。
RENAME_NOREPLACE

rename の newpath を 上 書 き し な い 。 newpath が す で に 存 在 す る 場 合 エ ラ ー を 返 す 。

RENAME_EXCHANGE

oldpath と newpath を ア ト ミ ッ ク に 入 れ 換 え る 。 両 方 の パ ス 名 が 存 在 し な け れ ば な ら な い が 、 フ ァ イ ル 種 別 は 異 な っ て い て も よ い (例 え ば 、 一 方 は 空 で な い デ ィ レ ク ト リ で 、 も う 一 方 は シ ン ボ リ ッ ク リ ン ク で あ る な ど )。

返 り 値

成 功 し た 場 合 は 0 が 返 さ れ る 。 エ ラ ー の 場 合 は −1 が 返 さ れ 、 errno が 適 切 に 設 定 さ れ る 。

エ ラ ー

EACCES

oldpath ま た は newpath を 含 ん で い る デ ィ レ ク ト リ の 書 き 込 み 許 可 が な い 。 ま た は 、 oldpath ま た は newpath の デ ィ レ ク ト リ 部 分 の ど れ か に 検 索 許 可 が な い 。 ま た は 、 oldpath が デ ィ レ ク ト リ で (.. エ ン ト リ ー を 更 新 す る の に 必 要 な ) 書 き 込 み 許 可 が な い (path_resolution(7) も 参 照 )。

EBUSY

oldpath ま た は newpath が デ ィ レ ク ト リ で 、 何 ら か の プ ロ セ ス が 使 用 中 (多 分 、 カ レ ン ト ワ ー キ ン グ デ ィ レ ク ト リ か 、 ル ー ト デ ィ レ ク ト リ か 、 読 み 込 み の た め に オ ー プ ン さ れ て い る か で ろ う ) も し く は 、 シ ス テ ム が 使 用 中 (例 え ば マ ウ ン ト ポ イ ン ト で あ る ) で あ り 、 シ ス テ ム が こ れ を エ ラ ー で あ る と 判 断 し た た め に rename が 失 敗 し た 。 (こ の よ う な 場 合 に EBUSY を 返 す こ と は 規 格 で は 要 求 さ れ て い な い 点 に 注 意 す る こ と 。 こ の よ う な 場 合 に 、 rename を と に か く 実 行 し て み る の は 何 の 問 題 も な い 。 た だ し 、 そ の よ う な 状 況 で 、 シ ス テ ム が 他 に 返 す エ ラ ー が な い 場 合 に は EBUSY を 返 す こ と が 許 さ れ て い る 。 )

EDQUOT

デ ィ ス ク ブ ロ ッ ク か inode が そ の フ ァ イ ル シ ス テ ム の ユ ー ザ ー ク ォ ー タ に 達 し て い た 。
EFAULT

oldpath や newpath が ア ク セ ス 可 能 な ア ド レ ス 空 間 の 外 を 指 し て い る 。

EINVAL

newpath が oldpath の パ ス 部 分 を 含 ん で い る 。 デ ィ レ ク ト リ を 自 分 自 身 の サ ブ デ ィ レ ク ト リ に 変 更 し よ う と し た 場 合 が ほ と ん ど で あ る 。

EISDIR

newpath は 存 在 し て い る デ ィ レ ク ト リ で あ る が 、 oldpath は デ ィ レ ク ト リ で な い 。

ELOOP

oldpath ま た は newpath を 解 決 す る 際 に 遭 遇 し た シ ン ボ リ ッ ク リ ン ク が 多 過 ぎ る 。

EMLINK

oldpath は 既 に 最 大 数 ま で の リ ン ク を 持 っ て い る か 、 そ れ が デ ィ レ ク ト リ で newpath を 含 ん で い る デ ィ レ ク ト リ が 最 大 数 ま で の リ ン ク を 持 っ て い る 。

ENAMETOOLONG

oldpath ま た は newpath が 長 過 ぎ る 。

ENOENT

oldpath と い う 名 前 の リ ン ク が 存 在 し な い 。 ま た は 、 newpath と い う デ ィ レ ク ト リ が 存 在 し な い 。 ま た は 、 oldpath か newpath が 空 の 文 字 列 で あ る 。

ENOMEM

十 分 な カ ー ネ ル メ モ リ ー が な い 。

ENOSPC そ の フ ァ イ ル を 含 ん で い る デ バ イ ス に 新 し い デ ィ レ ク ト リ エ ン ト リ ー を 作 成 す る た め の 空 き が な い 。

ENOTDIR

oldpath か newpath に 含 ま れ て い る デ ィ レ ク ト リ 部 分 が 実 際 に は デ ィ レ ク ト リ で な い 。 ま た は oldpath が デ ィ レ ク ト リ で 、 newpath が 存 在 し て デ ィ レ ク ト リ で な い 。

ENOTEMPTY ま た は EEXIST

newpath が 空 で な い デ ィ レ ク ト リ で あ る 。 す な わ ち "." と ".." 以 外 を 含 ん で い る 。

EPERM ま た は EACCES

oldpath の あ る デ ィ レ ク ト リ に ス テ ィ ッ キ ー ビ ッ ト (sticky bit) (S_ISVTX) が 設 定 さ れ て お り 、 プ ロ セ ス の 実 効 ユ ー ザ ー ID が 削 除 し よ う と す る フ ァ イ ル の ユ ー ザ ー ID と そ の フ ァ イ ル を 含 む デ ィ レ ク ト リ の ユ ー ザ ー ID の い ず れ と も 一 致 せ ず 、 か つ プ ロ セ ス に 特 権 が な い (Linux で は CAP_FOWNER ケ ー パ ビ リ テ ィ (capability) が な い )。 ま た は 、 newpath が す で に 存 在 す る フ ァ イ ル で 、 親 デ ィ レ ク ト リ に ス テ ィ ッ キ ー ビ ッ ト が 設 定 さ れ て お り 、 プ ロ セ ス の 実 効 ユ ー ザ ー ID が 置 き 換 え よ う と す る フ ァ イ ル の ユ ー ザ ー ID と そ の フ ァ イ ル を 含 む デ ィ レ ク ト リ の ユ ー ザ ー ID の い ず れ と も 一 致 せ ず 、 か つ プ ロ セ ス に 特 権 が な い (Linux で は CAP_FOWNER ケ ー パ ビ リ テ ィ が な い )。 ま た は oldpath と newpath が 存 在 す る フ ァ イ ル シ ス テ ム が 、 要 求 さ れ た 種 類 の 名 前 の 変 更 を サ ポ ー ト し て い な い 。

EROFS フ ァ イ ル が 読 み 込 み 専 用 の フ ァ イ ル シ ス テ ム に 存 在 す る 。

EXDEV

oldpath と newpath が 同 じ マ ウ ン ト さ れ た フ ァ イ ル シ ス テ ム に 存 在 し な い 。 (Linux は 1 つ の フ ァ イ ル シ ス テ ム を 複 数 の マ ウ ン ト 位 置 に マ ウ ン ト す る こ と を 許 可 し て い る 。 し か し rename() は 、 た と え 同 じ フ ァ イ ル シ ス テ ム で あ っ て も 、 別 々 の マ ウ ン ト 位 置 を 跨 い で は 動 作 し な い 。 )

renameat() と renameat2() で は 以 下 の エ ラ ー も 発 生 す る 。

EBADF

olddirfd か newdirfd が 有 効 な フ ァ イ ル デ ィ ス ク リ プ タ ー で な い 。

ENOTDIR

oldpath が 相 対 パ ス で 、 olddirfd が デ ィ レ ク ト リ 以 外 の フ ァ イ ル を 参 照 し て い る 。 ま た は newpath と newdirfd に 関 し て 同 じ 状 況 で あ る 。

renameat2() で は 以 下 の エ ラ ー も 発 生 す る 。

EEXIST

flags に RENAME_NOREPLACE が 指 定 さ れ て い る が 、 newpath が す で に 存 在 す る 。

EINVAL

flags に 無 効 な フ ラ グ が 指 定 さ れ た 。 RENAME_NOREPLACE と RENAME_EXCHANGE の 両 方 が 指 定 さ れ た 。

EINVAL

flags に フ ァ イ ル シ ス テ ム で サ ポ ー ト さ れ て い な い フ ラ グ が 指 定 さ れ た 。

ENOENT

flags に RENAME_EXCHANGE が 指 定 さ れ た が 、 newpath が 存 在 し な い 。

バ ー ジ ョ ン

renameat() は カ ー ネ ル 2.6.16 で Linux に 追 加 さ れ た 。 ラ イ ブ ラ リ に よ る サ ポ ー ト は バ ー ジ ョ ン 2.4 で glibc に 追 加 さ れ た 。

renameat2() は カ ー ネ ル 2.6.16 で Linux に 追 加 さ れ た 。

準 拠

rename(): 4.3BSD, C89, C99, POSIX.1−2001, POSIX.1−2008.

renameat(): POSIX.1−2008.

renameat2() は Linux 固 有 で あ る 。

注 意

glibc で の 注 意
renameat() が 利 用 で き な い 古 い カ ー ネ ル で は 、 glibc ラ ッ パ ー 関 数 は rename() を 使 用 す る モ ー ド に フ ォ ー ル バ ッ ク す る 。 oldpath と newpath が 相 対 パ ス の 場 合 、 glibc は olddirfd と newdirfd 引 き 数 に 対 応 す る /proc/self/fd の シ ン ボ リ ッ ク リ ン ク に 基 づ い て そ れ ぞ れ パ ス 名 を 構 成 す る 。

バ グ

NFS フ ァ イ ル シ ス テ ム で は 、 操 作 が 失 敗 し た か ら と い っ て 、 フ ァ イ ル の 名 前 が 変 更 で き な か っ た と 決 め て か か る こ と は で き な い 。 サ ー バ が rename 操 作 を 終 え て か ら ク ラ ッ シ ュ し た 場 合 、 サ ー バ が 再 び 立 ち 上 が っ た と き に 、 再 送 信 さ れ た RPC が 処 理 さ れ る が 、 こ れ は 失 敗 と な る 。 ア プ リ ケ ー シ ョ ン は こ の 問 題 を 正 し く 取 り 扱 う こ と が 期 待 さ れ て い る 。 同 様 の 問 題 に つ い て link(2) に も 書 か れ て い る 。

関 連 項 目

mv(1), chmod(2), link(2), symlink(2), unlink(2), path_resolution(7), symlink(7)

こ の 文 書 に つ い て

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