1RENAME(2)                  Linux Programmer's Manual                 RENAME(2)
2
3
4

NAME

6       rename, renameat, renameat2 - change the name or location of a file
7

SYNOPSIS

9       #include <stdio.h>
10
11       int rename(const char *oldpath, const char *newpath);
12
13       #include <fcntl.h>           /* Definition of AT_* constants */
14       #include <stdio.h>
15
16       int renameat(int olddirfd, const char *oldpath,
17                    int newdirfd, const char *newpath);
18       int renameat2(int olddirfd, const char *oldpath,
19                    int newdirfd, const char *newpath, unsigned int flags);
20
21   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
22
23       renameat():
24           Since glibc 2.10:
25               _POSIX_C_SOURCE >= 200809L
26           Before glibc 2.10:
27               _ATFILE_SOURCE
28
29       renameat2():
30           _GNU_SOURCE
31

DESCRIPTION

33       rename()  renames  a  file,  moving it between directories if required.
34       Any other hard links to the file (as created using link(2))  are  unaf‐
35       fected.  Open file descriptors for oldpath are also unaffected.
36
37       Various restrictions determine whether or not the rename operation suc‐
38       ceeds: see ERRORS below.
39
40       If newpath already exists, it will  be  atomically  replaced,  so  that
41       there is no point at which another process attempting to access newpath
42       will find it missing.  However, there will  probably  be  a  window  in
43       which both oldpath and newpath refer to the file being renamed.
44
45       If  oldpath  and  newpath are existing hard links referring to the same
46       file, then rename() does nothing, and returns a success status.
47
48       If newpath exists but the operation fails  for  some  reason,  rename()
49       guarantees to leave an instance of newpath in place.
50
51       oldpath can specify a directory.  In this case, newpath must either not
52       exist, or it must specify an empty directory.
53
54       If oldpath refers to a symbolic link, the link is renamed;  if  newpath
55       refers to a symbolic link, the link will be overwritten.
56
57   renameat()
58       The  renameat()  system  call  operates  in exactly the same way as re‐
59       name(), except for the differences described here.
60
61       If the pathname given in oldpath is relative, then  it  is  interpreted
62       relative  to  the directory referred to by the file descriptor olddirfd
63       (rather than relative to the current working directory of  the  calling
64       process, as is done by rename() for a relative pathname).
65
66       If oldpath is relative and olddirfd is the special value AT_FDCWD, then
67       oldpath is interpreted relative to the current working directory of the
68       calling process (like rename()).
69
70       If oldpath is absolute, then olddirfd is ignored.
71
72       The interpretation of newpath is as for oldpath, except that a relative
73       pathname is interpreted relative to the directory referred  to  by  the
74       file descriptor newdirfd.
75
76       See openat(2) for a