rename(2) - Japanese

Linux

2014-08-19

Aliases: renameat(2), renameat(2), renameat(2), renameat(2), renameat(2), renameat(2), renameat(2), renameat(2), renameat2(2), renameat2(2), renameat2(2), renameat2(2), renameat2(2), renameat2(2), renameat2(2)

manpages-ja-dev

Japanese version of the manual pages (for developers)

man-pages-ja

Japanese man (manual) pages from the Japanese Manual Project

manpages-dev

Manual pages about using GNU/Linux for development

man-pages

Linux kernel and C library user-space interface documentation

名前

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) にも書かれている。

この文書について

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

REFERENCED BY

lsof(1), fcntl(2), link(2), rmdir(2), symlink(2), unlink(2), remove(3), lsof(8), cpuset(7), inotify(7), symlink(7), cdb(1), cr_checkpoint(1), rfrename(1), libcpuset(3), ploop(8), since(1), renameat(2), STAR(1), ustar(1)