Man page - renameat2(2)

Packages contains this manual

Available languages:

en fr pl nl ja ru de

Manual

RENAME

名 前
書 式
説 明
renameat()
renameat2()
返 り 値
エ ラ ー
バ ー ジ ョ ン
準 拠
注 意
glibc で の 注 意
バ グ
関 連 項 目
こ の 文 書 に つ い て

名 前

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 以 降 :

_POSIX_C_SOURCE >= 200809L

glibc 2.10 よ り 前 :

_ATFILE_SOURCE

renameat2 ():

_GNU_SOURCE

説 明

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

Various restrictions determine whether or not the rename operation succeeds: see ERRORS below.

If newpath already exists, it will be atomically replaced, so that there is no point at which another process attempting to access newpath will find it missing. However, there will probably be a window in which both oldpath and newpath refer to the file being renamed.

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

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

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_EXCHANGE

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

RENAME_NOREPLACE

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

RENAME_NOREPLACE can’t be employed together with RENAME_EXCHANGE .

RENAME_NOREPLACE requires support from the underlying filesystem. Support for various filesystems was added as follows:

*

ext4 (Linux 3.15);

*

btrfs, shmem, cifs (Linux 3.17);

*

xfs (Linux 4.0);

*

Support for many other filesystems was added in Linux 4.9, including ext2, minix, reiserfs, jfs, vfat, and bpf.

RENAME_WHITEOUT (Linux 3.18 以 降 )

This operation makes sense only for overlay/union filesystem implementations.

Specifying RENAME_WHITEOUT creates a "whiteout" object at the source of the rename at the same time as performing the rename. The whole operation is atomic, so that if the rename succeeds then the whiteout will also have been created.

A "whiteout" is an object that has special meaning in union/overlay filesystem constructs. In these constructs, multiple layers exist and only the top one is ever modified. A whiteout on an upper layer will effectively hide a matching file in the lower layer, making it appear as if the file didn’t exist.

When a file that exists on the lower layer is renamed, the file is first copied up (if not already on the upper layer) and then renamed on the upper, read-write layer. At the same time, the source file needs to be "whiteouted" (so that the version of the source file in the lower layer is rendered invisible). The whole operation needs to be done atomically.

When not part of a union/overlay, the whiteout appears as a character device with a {0,0} device number. (Note that other union/overlay implementations may employ different methods for storing whiteout entries; specifically, BSD union mount employs a separate inode type, DT_WHT , which, while supported by some filesystems available in Linux, such as CODA and XFS, is ignored by the kernel’s whiteout support code, as of Linux 4.19, at least.)

RENAME_WHITEOUT requires the same privileges as creating a device node (i.e., the CAP_MKNOD capability).

RENAME_WHITEOUT can’t be employed together with RENAME_EXCHANGE .

RENAME_WHITEOUT requires support from the underlying filesystem. Among the filesystems that provide that support are tmpfs (since Linux 3.18), ext4 (since Linux 3.18), XFS (since Linux 4.1), f2fs (since Linux 4.2), btrfs (since Linux 4.7), and ubifs (since Linux 4.9).

返 り 値

成 功 し た 場 合 は 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 に 指 定 さ れ た 。

EINVAL

RENAME_NOREPLACE と RENAME_EXCHANGE の 両 方 が flags に 指 定 さ れ た 。

EINVAL

Both RENAME_WHITEOUT and RENAME_EXCHANGE were specified in flags .

EINVAL

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

ENOENT

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

EPERM

RENAME_WHITEOUT が flags に 指 定 さ れ た が 、 呼 び 出 し 元 が CAP_MKNOD ケ ー パ ビ リ テ ィ を 持 っ て い な い 。

バ ー ジ ョ ン

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

renameat2 () は カ ー ネ ル 3.15 で Linux に 追 加 さ れ た 。 ラ イ ブ ラ リ に よ る サ ポ ー ト は glibc 2.28 で 追 加 さ れ た 。

準 拠

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), rename (1), chmod (2), link (2), symlink (2), unlink (2), path_resolution (7), symlink (7)

こ の 文 書 に つ い て

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