]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
ac56b6a8 | 2 | .\" and Copyright (C) 1993 Michael Haardt; |
9cab982f MK |
3 | .\" and Copyright (C) 1993,1995 Ian Jackson |
4 | .\" and Copyright (C) 2006, 2014 Michael Kerrisk | |
fea681da | 5 | .\" |
93015253 | 6 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
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. | |
c13182ef | 15 | .\" |
fea681da MK |
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. | |
c13182ef | 23 | .\" |
fea681da MK |
24 | .\" Formatted or processed versions of this manual, if unaccompanied by |
25 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 26 | .\" %%%LICENSE_END |
fea681da MK |
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> | |
2d5d4b0d | 30 | .\" Modified Thu Mar 3 09:49:35 2005 by Michael Haardt <michael@moria.de> |
f6a4055f | 31 | .\" 2007-03-25, mtk, added various text to DESCRIPTION. |
fea681da | 32 | .\" |
ab99efdd | 33 | .TH RENAME 2 2014-04-19 "Linux" "Linux Programmer's Manual" |
fea681da | 34 | .SH NAME |
ab99efdd | 35 | rename, renameat, renameat2 \- change the name or location of a file |
fea681da | 36 | .SH SYNOPSIS |
9cab982f | 37 | .nf |
fea681da MK |
38 | .B #include <stdio.h> |
39 | .sp | |
40 | .BI "int rename(const char *" oldpath ", const char *" newpath ); | |
9cab982f MK |
41 | .sp |
42 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" | |
43 | .B #include <stdio.h> | |
44 | .sp | |
45 | .BI "int renameat(int " olddirfd ", const char *" oldpath , | |
46 | .BI " int " newdirfd ", const char *" newpath ); | |
ab99efdd MS |
47 | |
48 | .BI "int renameat2(int " olddirfd ", const char *" oldpath , | |
84f573db MK |
49 | .BI " int " newdirfd ", const char *" newpath \ |
50 | ", unsigned int " flags ); | |
9cab982f MK |
51 | .fi |
52 | .sp | |
53 | .in -4n | |
54 | Feature Test Macro Requirements for glibc (see | |
55 | .BR feature_test_macros (7)): | |
56 | .in | |
57 | .sp | |
58 | .BR renameat (): | |
59 | .PD 0 | |
60 | .ad l | |
61 | .RS 4 | |
62 | .TP 4 | |
63 | Since glibc 2.10: | |
64 | _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L | |
65 | .TP | |
66 | Before glibc 2.10: | |
67 | _ATFILE_SOURCE | |
ab99efdd | 68 | .\" FIXME need to define FTMs for renameat2(), once it hits glibc |
9cab982f MK |
69 | .RE |
70 | .ad | |
71 | .PD | |
fea681da | 72 | .SH DESCRIPTION |
e511ffb6 | 73 | .BR rename () |
fea681da | 74 | renames a file, moving it between directories if required. |
fea681da MK |
75 | Any other hard links to the file (as created using |
76 | .BR link (2)) | |
77 | are unaffected. | |
f6a4055f MK |
78 | Open file descriptors for |
79 | .I oldpath | |
80 | are also unaffected. | |
fea681da MK |
81 | |
82 | If | |
83 | .I newpath | |
afb3d50c | 84 | already exists, it will be atomically replaced (subject to |
e9496f74 | 85 | a few conditions; see ERRORS below), so that there is |
fea681da MK |
86 | no point at which another process attempting to access |
87 | .I newpath | |
88 | will find it missing. | |
89 | ||
f6a4055f MK |
90 | If |
91 | .I oldpath | |
92 | and | |
93 | .I newpath | |
94 | are existing hard links referring to the same file, then | |
95 | .BR rename () | |
96 | does nothing, and returns a success status. | |
97 | ||
fea681da MK |
98 | If |
99 | .I newpath | |
afb3d50c | 100 | exists but the operation fails for some reason, |
e511ffb6 | 101 | .BR rename () |
fea681da MK |
102 | guarantees to leave an instance of |
103 | .I newpath | |
104 | in place. | |
105 | ||
f6a4055f MK |
106 | .I oldpath |
107 | can specify a directory. | |
c13182ef | 108 | In this case, |
f6a4055f MK |
109 | .I newpath |
110 | must either not exist, or it must specify an empty directory. | |
111 | ||
fea681da MK |
112 | However, when overwriting there will probably be a window in which |
113 | both | |
114 | .I oldpath | |
115 | and | |
116 | .I newpath | |
117 | refer to the file being renamed. | |
118 | ||
119 | If | |
120 | .I oldpath | |
afb3d50c | 121 | refers to a symbolic link, the link is renamed; if |
fea681da | 122 | .I newpath |
afb3d50c | 123 | refers to a symbolic link, the link will be overwritten. |
9cab982f MK |
124 | .SS renameat () |
125 | The | |
126 | .BR renameat () | |
127 | system call operates in exactly the same way as | |
cadd38ba | 128 | .BR rename (), |
9cab982f MK |
129 | except for the differences described here. |
130 | ||
131 | If the pathname given in | |
132 | .I oldpath | |
133 | is relative, then it is interpreted relative to the directory | |
134 | referred to by the file descriptor | |
135 | .I olddirfd | |
136 | (rather than relative to the current working directory of | |
137 | the calling process, as is done by | |
cadd38ba | 138 | .BR rename () |
9cab982f MK |
139 | for a relative pathname). |
140 | ||
141 | If | |
142 | .I oldpath | |
143 | is relative and | |
144 | .I olddirfd | |
145 | is the special value | |
146 | .BR AT_FDCWD , | |
147 | then | |
148 | .I oldpath | |
149 | is interpreted relative to the current working | |
150 | directory of the calling process (like | |
cadd38ba | 151 | .BR rename ()). |
9cab982f MK |
152 | |
153 | If | |
154 | .I oldpath | |
155 | is absolute, then | |
156 | .I olddirfd | |
157 | is ignored. | |
158 | ||
159 | The interpretation of | |
160 | .I newpath | |
161 | is as for | |
162 | .IR oldpath , | |
163 | except that a relative pathname is interpreted relative | |
164 | to the directory referred to by the file descriptor | |
165 | .IR newdirfd . | |
166 | ||
167 | See | |
168 | .BR openat (2) | |
169 | for an explanation of the need for | |
170 | .BR renameat (). | |
ab99efdd MS |
171 | .SS renameat2() |
172 | .BR renameat2 () | |
173 | has an additional | |
174 | .I flags | |
175 | argument. | |
176 | A | |
177 | .BR renameat2 () | |
178 | call with a zero | |
179 | .I flags | |
180 | argument is equivalent to | |
181 | .BR renameat (). | |
182 | ||
183 | The | |
184 | .I flags | |
185 | argument is a bit mask consisting of zero or more of the following flags: | |
186 | .TP | |
187 | .B RENAME_NOREPLACE | |
188 | Don't overwrite | |
189 | .IR newpath . | |
190 | of the rename. | |
191 | Return an error if | |
192 | .IR newpath | |
193 | already exists. | |
194 | .TP | |
195 | .B RENAME_EXCHANGE | |
196 | Atomically exchange | |
197 | .IR oldpath | |
198 | and | |
199 | .IR newpath . | |
200 | Both pathnames must exist | |
201 | but may be of different types (e.g., one could be a non-empty directory | |
202 | and the other a symbolic link). | |
47297adb | 203 | .SH RETURN VALUE |
c13182ef MK |
204 | On success, zero is returned. |
205 | On error, \-1 is returned, and | |
fea681da MK |
206 | .I errno |
207 | is set appropriately. | |
208 | .SH ERRORS | |
209 | .TP | |
210 | .B EACCES | |
211 | Write permission is denied for the directory containing | |
212 | .I oldpath | |
213 | or | |
214 | .IR newpath , | |
215 | or, search permission is denied for one of the directories | |
216 | in the path prefix of | |
217 | .I oldpath | |
218 | or | |
219 | .IR newpath , | |
220 | or | |
221 | .I oldpath | |
222 | is a directory and does not allow write permission (needed to update | |
223 | the | |
836f07c1 | 224 | .I .. |
fea681da MK |
225 | entry). |
226 | (See also | |
ad7cc990 | 227 | .BR path_resolution (7).) |
fea681da MK |
228 | .TP |
229 | .B EBUSY | |
230 | The rename fails because | |
231 | .IR oldpath " or " newpath | |
232 | is a directory that is in use by some process (perhaps as | |
233 | current working directory, or as root directory, or because | |
234 | it was open for reading) or is in use by the system | |
235 | (for example as mount point), while the system considers | |
236 | this an error. | |
682edefb | 237 | (Note that there is no requirement to return |
0daa9e92 | 238 | .B EBUSY |
682edefb | 239 | in such |
5503c85e MK |
240 | cases\(emthere is nothing wrong with doing the rename anyway\(embut |
241 | it is allowed to return | |
682edefb MK |
242 | .B EBUSY |
243 | if the system cannot otherwise | |
fea681da MK |
244 | handle such situations.) |
245 | .TP | |
a1f01685 | 246 | .B EDQUOT |
9ee4a2b6 | 247 | The user's quota of disk blocks on the filesystem has been exhausted. |
a1f01685 | 248 | .TP |
fea681da MK |
249 | .B EFAULT |
250 | .IR oldpath " or " newpath " points outside your accessible address space." | |
251 | .TP | |
252 | .B EINVAL | |
253 | The new pathname contained a path prefix of the old, or, more generally, | |
254 | an attempt was made to make a directory a subdirectory of itself. | |
255 | .TP | |
256 | .B EISDIR | |
257 | .I newpath | |
258 | is an existing directory, but | |
259 | .I oldpath | |
260 | is not a directory. | |
261 | .TP | |
262 | .B ELOOP | |
263 | Too many symbolic links were encountered in resolving | |
264 | .IR oldpath " or " newpath . | |
265 | .TP | |
266 | .B EMLINK | |
267 | .I oldpath | |
268 | already has the maximum number of links to it, or | |
269 | it was a directory and the directory containing | |
270 | .I newpath | |
271 | has the maximum number of links. | |
272 | .TP | |
273 | .B ENAMETOOLONG | |
274 | .IR oldpath " or " newpath " was too long." | |
275 | .TP | |
276 | .B ENOENT | |
3d81b967 MK |
277 | The link named by |
278 | .I oldpath | |
279 | does not exist; | |
280 | or, a directory component in | |
281 | .I newpath | |
282 | does not exist; | |
283 | or, | |
284 | .I oldpath | |
285 | or | |
286 | .I newpath | |
287 | is an empty string. | |
fea681da MK |
288 | .TP |
289 | .B ENOMEM | |
290 | Insufficient kernel memory was available. | |
291 | .TP | |
292 | .B ENOSPC | |
293 | The device containing the file has no room for the new directory | |
294 | entry. | |
295 | .TP | |
296 | .B ENOTDIR | |
297 | A component used as a directory in | |
298 | .IR oldpath " or " newpath | |
299 | is not, in fact, a directory. | |
300 | Or, | |
301 | .I oldpath | |
302 | is a directory, and | |
303 | .I newpath | |
304 | exists but is not a directory. | |
305 | .TP | |
306 | .BR ENOTEMPTY " or " EEXIST | |
0daa9e92 | 307 | .I newpath |
aa796481 | 308 | is a nonempty directory, that is, contains entries other than "." and "..". |
fea681da MK |
309 | .TP |
310 | .BR EPERM " or " EACCES | |
311 | The directory containing | |
312 | .I oldpath | |
313 | has the sticky bit | |
314 | .RB ( S_ISVTX ) | |
315 | set and the process's effective user ID is neither | |
316 | the user ID of the file to be deleted nor that of the directory | |
317 | containing it, and the process is not privileged | |
318 | (Linux: does not have the | |
319 | .B CAP_FOWNER | |
320 | capability); | |
321 | or | |
322 | .I newpath | |
323 | is an existing file and the directory containing it has the sticky bit set | |
324 | and the process's effective user ID is neither the user ID of the file | |
325 | to be replaced nor that of the directory containing it, | |
326 | and the process is not privileged | |
327 | (Linux: does not have the | |
328 | .B CAP_FOWNER | |
329 | capability); | |
9ee4a2b6 | 330 | or the filesystem containing |
0daa9e92 | 331 | .I pathname |
fea681da MK |
332 | does not support renaming of the type requested. |
333 | .TP | |
334 | .B EROFS | |
9ee4a2b6 | 335 | The file is on a read-only filesystem. |
fea681da MK |
336 | .TP |
337 | .B EXDEV | |
338 | .IR oldpath " and " newpath | |
9ee4a2b6 MK |
339 | are not on the same mounted filesystem. |
340 | (Linux permits a filesystem to be mounted at multiple points, but | |
2777b1ca | 341 | .BR rename () |
2d5d4b0d | 342 | does not work across different mount points, |
9ee4a2b6 | 343 | even if the same filesystem is mounted on both.) |
9cab982f MK |
344 | .PP |
345 | The following additional errors can occur for | |
ab99efdd MS |
346 | .BR renameat () |
347 | and | |
348 | .BR renameat2 (): | |
9cab982f MK |
349 | .TP |
350 | .B EBADF | |
351 | .I olddirfd | |
352 | or | |
353 | .I newdirfd | |
354 | is not a valid file descriptor. | |
355 | .TP | |
356 | .B ENOTDIR | |
357 | .I oldpath | |
358 | is relative and | |
359 | .I olddirfd | |
360 | is a file descriptor referring to a file other than a directory; | |
361 | or similar for | |
362 | .I newpath | |
363 | and | |
364 | .I newdirfd | |
ab99efdd MS |
365 | .PP |
366 | The following additional errors can occur for | |
367 | .BR renameat2 (): | |
368 | .TP | |
369 | .B EEXIST | |
370 | .I flags | |
371 | contains | |
372 | .B RENAME_NOREPLACE | |
373 | and | |
374 | .I newpath | |
375 | already exists. | |
376 | .TP | |
377 | .B EINVAL | |
5c1517fa MK |
378 | An invalid flag was specified in |
379 | .IR flags , | |
380 | or both | |
381 | .B RENAME_NOREPLACE | |
382 | and | |
383 | .B RENAME_EXCHANGE | |
384 | were specified. | |
ab99efdd MS |
385 | .TP |
386 | .B EINVAL | |
387 | The filesystem does not support one of the flags in | |
388 | .IR flags . | |
389 | .TP | |
390 | .B ENOENT | |
391 | .I flags | |
8f60952e | 392 | contains |
ab99efdd | 393 | .B RENAME_EXCHANGE |
8f60952e MK |
394 | and |
395 | .IR newpath | |
396 | does not exist. | |
9cab982f MK |
397 | .SH VERSIONS |
398 | .BR renameat () | |
399 | was added to Linux in kernel 2.6.16; | |
400 | library support was added to glibc in version 2.4. | |
4e6c4ab2 MK |
401 | |
402 | .BR renameat2 () | |
403 | was added to Linux in kernel 3.15. | |
404 | .\" FIXME glibc support is pending. | |
47297adb | 405 | .SH CONFORMING TO |
9cab982f | 406 | .BR rename (): |
1e8473f4 | 407 | 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008. |
9cab982f MK |
408 | |
409 | .BR renameat (): | |
410 | POSIX.1-2008. | |
4e6c4ab2 MK |
411 | |
412 | .BR renameat2() | |
413 | is Linux-specific. | |
fea681da | 414 | .SH BUGS |
9ee4a2b6 | 415 | On NFS filesystems, you can not assume that if the operation |
afb3d50c | 416 | failed, the file was not renamed. |
c13182ef | 417 | If the server does the rename operation |
fea681da | 418 | and then crashes, the retransmitted RPC which will be processed when the |
c13182ef MK |
419 | server is up again causes a failure. |
420 | The application is expected to | |
421 | deal with this. | |
422 | See | |
fea681da MK |
423 | .BR link (2) |
424 | for a similar problem. | |
47297adb | 425 | .SH SEE ALSO |
fea681da MK |
426 | .BR mv (1), |
427 | .BR chmod (2), | |
428 | .BR link (2), | |
fea681da | 429 | .BR symlink (2), |
ad7cc990 | 430 | .BR unlink (2), |
a9cfde1d | 431 | .BR path_resolution (7), |
ad22ad55 | 432 | .BR symlink (7) |