release/man2/rename.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\"             and Copyright (C) 1993 Michael Haardt;
   3 .\"             and Copyright (C) 1993,1995 Ian Jackson
   4 .\"             and Copyright (C) 2006, 2014 Michael Kerrisk
   5 .\"
   6 .\" %%%LICENSE_START(VERBATIM)
   7 .\" Permission is granted to make and distribute verbatim copies of this
   8 .\" manual provided the copyright notice and this permission notice are
   9 .\" preserved on all copies.
  10 .\"
  11 .\" Permission is granted to copy and distribute modified versions of this
  12 .\" manual under the conditions for verbatim copying, provided that the
  13 .\" entire resulting derived work is distributed under the terms of a
  14 .\" permission notice identical to this one.
  15 .\"
  16 .\" Since the Linux kernel and libraries are constantly changing, this
  17 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  18 .\" responsibility for errors or omissions, or for damages resulting from
  19 .\" the use of the information contained herein.  The author(s) may not
  20 .\" have taken the same level of care in the production of this manual,
  21 .\" which is licensed free of charge, as they might when working
  22 .\" professionally.
  23 .\"
  24 .\" Formatted or processed versions of this manual, if unaccompanied by
  25 .\" the source, must acknowledge the copyright and authors of this work.
  26 .\" %%%LICENSE_END
  27 .\"
  28 .\" Modified Sat Jul 24 00:35:52 1993 by Rik Faith <faith@cs.unc.edu>
  29 .\" Modified Thu Jun  4 12:21:13 1998 by Andries Brouwer <aeb@cwi.nl>
  30 .\" Modified Thu Mar  3 09:49:35 2005 by Michael Haardt <michael@moria.de>
  31 .\" 2007-03-25, mtk, added various text to DESCRIPTION.
  32 .\"
  33 .\"*******************************************************************
  34 .\"
  35 .\" This file was generated with po4a. Translate the source file.
  36 .\"
  37 .\"*******************************************************************
  38 .\"
  39 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  40 .\"         all rights reserved.
  41 .\" Translated Fri Dec 12 00:15:52 JST 1997
  42 .\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  43 .\" Updated & Modified Thu Feb 10 07:23:59 JST 2005
  44 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>
  45 .\" Updated & Modified Fri Apr 22 03:21:04 JST 2005 by Yuichi SATO
  46 .\" Updated 2007-05-04, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.44
  47 .\" Updated 2009-04-24, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.20
  48 .\" Updated 2013-05-01, Akihiro MOTOKI <amotoki@gmail.com>
  49 .\" Updated 2013-05-06, Akihiro MOTOKI <amotoki@gmail.com>
  50 .\"
  51 .TH RENAME 2 2014\-08\-19 Linux "Linux Programmer's Manual"
  52 .SH 名前
  53 rename, renameat, renameat2 \- ファイルの名前や位置を変更する
  54 .SH 書式
  55 .nf
  56 \fB#include <stdio.h>\fP
  57 .sp
  58 \fBint rename(const char *\fP\fIoldpath\fP\fB, const char *\fP\fInewpath\fP\fB);\fP
  59 .sp
  60 \fB#include <fcntl.h>           \fP/* AT_* 定数の定義 */
  61 \fB#include <stdio.h>\fP
  62 .sp
  63 \fBint renameat(int \fP\fIolddirfd\fP\fB, const char *\fP\fIoldpath\fP\fB,\fP
  64 \fB             int \fP\fInewdirfd\fP\fB, const char *\fP\fInewpath\fP\fB);\fP
  65
  66 \fBint renameat2(int \fP\fIolddirfd\fP\fB, const char *\fP\fIoldpath\fP\fB,\fP
  67 \fB              int \fP\fInewdirfd\fP\fB, const char *\fP\fInewpath\fP\fB, unsigned int \fP\fIflags\fP\fB);\fP
  68 .fi
  69 .sp
  70 .in -4n
  71 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  72 .in
  73 .sp
  74 \fBrenameat\fP():
  75 .PD 0
  76 .ad l
  77 .RS 4
  78 .TP  4
  79 glibc 2.10 以降:
  80 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  81 .TP
  82 glibc 2.10 より前:
  83 .\" FIXME . need to define FTMs for renameat2(), once it hits glibc
  84 _ATFILE_SOURCE
  85 .RE
  86 .ad
  87 .PD
  88 .SH 説明
  89 \fBrename\fP()  はファイルの名前を変更し、必要ならばディレクトリ間の移動を行なう。 そのファイルに対する (\fBlink\fP(2)
  90 を使用して作られた) 他のハードリンク (hard link) には影響はない。 オープン済の \fIoldpath\fP
  91 に対するファイルディスクリプタにも影響はない。
  92
  93 \fInewpath\fP が既に存在する場合、それは不可分操作で (atomically) 置き換えられる (ただし、いくつかの条件がある;
  94 以下の「エラー」のセクションを参照)。 そのため、 \fInewpath\fP にアクセスしようとしている他のプロセスがファイルを見失うことはない (訳註:
  95 常にアクセス可能である)。
  96
  97 \fIoldpath\fP と \fInewpath\fP がどちらも既存のハードリンクで、同じファイルを参照している場合、 \fBrename\fP()
  98 は何も行わず、ステータスとして成功を返す。
  99
 100 \fInewpath\fP が存在し、何らかの理由で操作が失敗した場合、 \fBrename\fP()  は \fInewpath\fP
 101 の実体を元のまま残すことを保証する。
 102
 103 \fIoldpath\fP にはディレクトリを指定することもできる。 この場合、 \fInewpath\fP は存在しないか、空のディレクトリでなければならない。
 104
 105 一方で、上書きを行なう場合は、rename が行なわれるファイルを \fIoldpath\fP と \fInewpath\fP
 106 の両方で参照できる瞬間がおそらく存在する。
 107
 108 \fIoldpath\fP がシンボリックリンク (symbolic link) を参照している場合は、 リンクの名前が変更される。 また、
 109 \fInewpath\fP がシンボリックリンクを参照している場合は、リンクが上書きされる。
 110 .SS renameat()
 111 \fBrenameat\fP() システムコールは \fBrename\fP() と全く同様に動作するが、以下で説明する点が異なる。
 112
 113 \fIoldpath\fP で指定されたパス名が相対パスの場合、このパス名はファイルディスクリプター \fIolddirfd\fP
 114 が参照するディレクトリに対する相対パスと解釈される (\fBrename\fP(2)
 115 に相対パス名を渡した場合のように、呼び出したプロセスのカレントワーキングディレクトリに対する相対パスではない)。
 116
 117 \fIoldpath\fP で指定されたパス名が相対パスで、 \fIolddirfd\fP が特別な値 \fBAT_FDCWD\fP の場合、 (\fBrename\fP(2)
 118 と同様に) \fIoldpath\fP は呼び出したプロセスのカレントワーキングディレクトリに対する相対パスと解釈される。
 119
 120 \fIoldpath\fP で指定されたパス名が絶対パスの場合、 \fIolddirfd\fP は無視される。
 121
 122 \fInewpath\fP の解釈は \fIoldpath\fP と同じである。 相対パスのパス名がファイルディスクリプター \fInewdirfd\fP
 123 が参照するディレクトリと解釈される点だけが異なる。
 124
 125 \fBrenameat\fP() の必要性についての説明については \fBopenat\fP(2) を参照。
 126 .SS renameat2()
 127 \fBrenameat2\fP() には追加の \fIflags\fP 引き数がある。 \fIflags\fP 引き数が 0 の \fBrenameat2\fP()
 128 の呼び出しは \fBrenameat\fP() と等価である。
 129
 130 \fIflags\fP 引き数は、以下のフラグの 0 個以上のビットマスクである。
 131 .TP
 132 \fBRENAME_NOREPLACE\fP
 133 rename の \fInewpath\fP を上書きしない。 \fInewpath\fP がすでに存在する場合エラーを返す。
 134 .TP
 135 \fBRENAME_EXCHANGE\fP
 136 \fIoldpath\fP と \fInewpath\fP をアトミックに入れ換える。 両方のパス名が存在しなければならないが、 ファイル種別は異なっていてもよい
 137 (例えば、一方は空でないディレクトリで、もう一方はシンボリックリンクであるなど)。
 138 .SH 返り値
 139 成功した場合は 0 が返される。エラーの場合は \-1 が返され、 \fIerrno\fP が適切に設定される。
 140 .SH エラー
 141 .TP
 142 \fBEACCES\fP
 143 \fIoldpath\fP または \fInewpath\fP を含んでいるディレクトリの書き込み許可がない。 または、 \fIoldpath\fP または
 144 \fInewpath\fP のディレクトリ部分のどれかに検索許可がない。 または、 \fIoldpath\fP がディレクトリで (\fI..\fP
 145 エントリを更新するのに必要な) 書き込み許可がない (\fBpath_resolution\fP(7)  も参照)。
 146 .TP
 147 \fBEBUSY\fP
 148 \fIoldpath\fP または \fInewpath\fP がディレクトリで、何らかのプロセスが使用中
 149 (多分、カレントワーキングディレクトリか、ルートディレクトリか、 読み込みのためにオープンされているかでろう)  もしくは、システムが使用中
 150 (例えばマウントポイントである)  であり、システムがこれをエラーであると判断したために rename が失敗した。 (このような場合に
 151 \fBEBUSY\fP を返すことは規格では要求されていない点に注意すること。 このような場合に、rename をとにかく実行してみるのは何の問題もない。
 152 ただし、そのような状況で、システムが他に返すエラーがない場合には \fBEBUSY\fP を返すことが許されている。)
 153 .TP
 154 \fBEDQUOT\fP
 155 ディスクブロックか inode がそのファイルシステムのユーザクォータに達していた。
 156 .TP
 157 \fBEFAULT\fP
 158 \fIoldpath\fP や \fInewpath\fP がアクセス可能なアドレス空間の外を指している。
 159 .TP
 160 \fBEINVAL\fP
 161 \fInewpath\fP が \fIoldpath\fP のパス部分を含んでいる。ディレクトリを自分自身のサブディレクトリに
 162 変更しようとした場合がほとんどである。
 163 .TP
 164 \fBEISDIR\fP
 165 \fInewpath\fP は存在しているディレクトリであるが、 \fIoldpath\fP はディレクトリでない。
 166 .TP
 167 \fBELOOP\fP
 168 \fIoldpath\fP または \fInewpath\fP を解決する際に遭遇したシンボリックリンクが多過ぎる。
 169 .TP
 170 \fBEMLINK\fP
 171 \fIoldpath\fP は既に最大数までのリンクを持っているか、それがディレクトリで \fInewpath\fP
 172 を含んでいるディレクトリが最大数までのリンクを持っている。
 173 .TP
 174 \fBENAMETOOLONG\fP
 175 \fIoldpath\fP または \fInewpath\fP が長過ぎる。
 176 .TP
 177 \fBENOENT\fP
 178 \fIoldpath\fP という名前のリンクが存在しない。 または、 \fInewpath\fP というディレクトリが存在しない。 または、 \fIoldpath\fP
 179 か \fInewpath\fP が空の文字列である。
 180 .TP
 181 \fBENOMEM\fP
 182 十分なカーネルメモリーがない。
 183 .TP
 184 \fBENOSPC\fP
 185 そのファイルを含んでいるデバイスに新しいディレクトリエントリを 作成するための空きがない。
 186 .TP
 187 \fBENOTDIR\fP
 188 \fIoldpath\fP か \fInewpath\fP に含まれているディレクトリ部分が 実際にはディレクトリでない。 または \fIoldpath\fP
 189 がディレクトリで、 \fInewpath\fP が存在してディレクトリでない。
 190 .TP
 191 \fBENOTEMPTY  または  EEXIST\fP
 192 \fInewpath\fP が空でないディレクトリである。すなわち "." と ".." 以外を含んでいる。
 193 .TP
 194 \fBEPERM\fP または \fBEACCES\fP
 195 \fIoldpath\fP のあるディレクトリにスティッキービット (sticky bit)  (\fBS_ISVTX\fP)  が設定されており、
 196 プロセスの実効ユーザー ID が 削除しようとするファイルのユーザー ID と そのファイルを含むディレクトリのユーザー ID
 197 のいずれとも一致せず、かつ プロセスに特権がない (Linux では \fBCAP_FOWNER\fP ケーパビリティ (capability) がない)。
 198 または、 \fInewpath\fP がすでに存在するファイルで、親ディレクトリにスティッキービットが設定されており、 プロセスの実効ユーザー ID が
 199 置き換えようとするファイルのユーザー ID と そのファイルを含むディレクトリのユーザー ID のいずれとも一致せず、かつ プロセスに特権がない
 200 (Linux では \fBCAP_FOWNER\fP ケーパビリティがない)。 または \fIoldpath\fP と \fInewpath\fP
 201 が存在するファイルシステムが、要求された種類の名前の変更を サポートしていない。
 202 .TP
 203 \fBEROFS\fP
 204 ファイルが読み込み専用のファイルシステムに存在する。
 205 .TP
 206 \fBEXDEV\fP
 207 \fIoldpath\fP と \fInewpath\fP が同じマウントされたファイルシステムに存在しない。 (Linux は 1
 208 つのファイルシステムを複数のマウント位置に マウントすることを許可している。 しかし \fBrename\fP()
 209 は、たとえ同じファイルシステムであっても、 別々のマウント位置を跨いでは動作しない。)
 210 .PP
 211 \fBrenameat\fP() と \fBrenameat2\fP() では以下のエラーも発生する。
 212 .TP
 213 \fBEBADF\fP
 214 \fIolddirfd\fP か \fInewdirfd\fP が有効なファイルディスクリプタでない。
 215 .TP
 216 \fBENOTDIR\fP
 217 \fIoldpath\fP が相対パスで、 \fIolddirfd\fP がディレクトリ以外のファイルを参照している。または \fInewpath\fP と
 218 \fInewdirfd\fP に関して同じ状況である。
 219 .PP
 220 \fBrenameat2\fP() では以下のエラーも発生する。
 221 .TP
 222 \fBEEXIST\fP
 223 \fIflags\fP に \fBRENAME_NOREPLACE\fP が指定されているが、 \fInewpath\fP がすでに存在する。
 224 .TP
 225 \fBEINVAL\fP
 226 \fIflags\fP に無効なフラグが指定された。 \fBRENAME_NOREPLACE\fP と \fBRENAME_EXCHANGE\fP の両方が指定された。
 227 .TP
 228 \fBEINVAL\fP
 229 \fIflags\fP にファイルシステムでサポートされていないフラグが指定された。
 230 .TP
 231 \fBENOENT\fP
 232 \fIflags\fP に \fBRENAME_EXCHANGE\fP が指定されたが、 \fInewpath\fP が存在しない。
 233 .SH バージョン
 234 \fBrenameat\fP()  はカーネル 2.6.16 で Linux に追加された。 ライブラリによるサポートはバージョン 2.4 で glibc
 235 に追加された。
 236
 237 .\" FIXME . glibc support is pending.
 238 \fBrenameat2\fP()  はカーネル 2.6.16 で Linux に追加された。
 239 .SH 準拠
 240 \fBrename\fP(): 4.3BSD, C89, C99, POSIX.1\-2001, POSIX.1\-2008.
 241
 242 \fBrenameat\fP(): POSIX.1\-2008.
 243
 244 \fBrenameat2\fP()  は Linux 固有である。
 245 .SH 注意
 246 .SS "glibc での注意"
 247 \fBrenameat\fP() が利用できない古いカーネルでは、 glibc ラッパー関数は \fBrename\fP() を使用するモードにフォールバックする。
 248 \fIoldpath\fP と \fInewpath\fP が相対パスの場合、 glibc は \fIolddirfd\fP と \fInewdirfd\fP 引き数に対応する
 249 \fI/proc/self/fd\fP のシンボリックリンクに基づいてそれぞれパス名を構成する。
 250 .SH バグ
 251 NFS ファイルシステムでは、操作が失敗したからといって、 ファイルの名前が変更できなかったと決めてかかることはできない。 サーバが rename
 252 操作を終えてからクラッシュした場合、 サーバが再び立ち上がったときに、 再送信された RPC が処理されるが、これは失敗となる。
 253 アプリケーションはこの問題を正しく取り扱うことが期待されている。 同様の問題について \fBlink\fP(2)  にも書かれている。
 254 .SH 関連項目
 255 \fBmv\fP(1), \fBchmod\fP(2), \fBlink\fP(2), \fBsymlink\fP(2), \fBunlink\fP(2),
 256 \fBpath_resolution\fP(7), \fBsymlink\fP(7)
 257 .SH この文書について
 258 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.77 の一部
 259 である。プロジェクトの説明とバグ報告に関する情報は
 260 http://www.kernel.org/doc/man\-pages/ に書かれている。