Other Alias
renameat書式
#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);
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) を参照。
返り値
成功した場合は 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() では以下のエラーも発生する。
- EBADF
- olddirfd か newdirfd が有効なファイルディスクリプタでない。
- ENOTDIR
- oldpath が相対パスで、 olddirfd がディレクトリ以外のファイルを参照している。または newpath と newdirfd に関して同じ状況である。
バージョン
renameat() はカーネル 2.6.16 で Linux に追加された。 ライブラリによるサポートはバージョン 2.4 で glibc に追加された。準拠
rename(): 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008.renameat(): POSIX.1-2008.
バグ
NFS ファイルシステムでは、操作が失敗したからといって、 ファイルの名前が変更できなかったと決めてかかることはできない。 サーバが rename 操作を終えてからクラッシュした場合、 サーバが再び立ち上がったときに、 再送信された RPC が処理されるが、これは失敗となる。 アプリケーションはこの問題を正しく取り扱うことが期待されている。 同様の問題について link(2) にも書かれている。この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.65 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。