1rename(2) System Calls rename(2)
2
6 rename, renameat - change the name of a file
7
9 #include <stdio.h>
10 int rename(const char *old, const char *new);
12 #include <unistd.h>
15 int renameat(int fromfd, const char *old, int tofd,
17 const char *new);
18 XPG3
21 #include <unistd.h>
22 int rename(const char *old, const char *new);
24
27 The rename() function changes the name of a file. The old argument
28 points to the pathname of the file to be renamed. The new argument
29 points to the new path name of the file.
30 The renameat() function renames an entry in a directory, possibly mov‐
33 ing the entry into a different directory. See fsattr(5). If the old
34 argument is an absolute path, the fromfd is ignored. Otherwise it is
35 resolved relative to the fromfd argument rather than the current work‐
36 ing directory. Similarly, if the new argument is not absolute, it is
37 resolved relative to the tofd argument. If either fromfd or tofd have
38 the value AT_FDCWD, defined in <fcntl.h>, and their respective paths
39 are relative, the path is resolved relative to the current working
40 directory.
41 Current implementation restrictions will cause the renameat() function
44 to return an error if an attempt is made to rename an extended
45 attribute file to a regular (non-attribute) file, or to rename a regu‐
46 lar file to an extended attribute file.
47 If old and new both refer to the same existing file, the rename() and
50 renameat() functions return successfully and performs no other action.
51 If old points to the pathname of a file that is not a directory, new
54 must not point to the pathname of a directory. If the link named by new
55 exists, it will be removed and old will be renamed to new. In this
56 case, a link named new must remain visible to other processes through‐
57 out the renaming operation and will refer to either the file referred
58 to by new or the file referred to as old before the operation began.
59 If old points to the pathname of a directory, new must not point to
62 the pathname of a file that is not a directory. If the directory named
63 by new exists, it will be removed and old will be renamed to new. In
64 this case, a link named new will exist throughout the renaming opera‐
65 tion and will refer to either the file referred to by new or the file
66 referred to as old before the operation began. Thus, if new names an
67 existing directory, it must be an empty directory.
68 The new pathname must not contain a path prefix that names old. Write
71 access permission is required for both the directory containing old and
72 the directory containing new. If old points to the pathname of a
73 directory, write access permission is required for the directory named
74 by old, and, if it exists, the directory named by new.
75 If the directory containing old has the sticky bit set, at least one
78 of the following conditions listed below must be true:
79 o the user must own old
81 o the user must own the directory containing old
83 o old must be writable by the user
85 o the user must be a privileged user
87 If new exists, and the directory containing new is writable and has the
90 sticky bit set, at least one of the following conditions must be true:
91 o the user must own new
93 o the user must own the directory containing new
95 o new must be writable by the user
97 o the user must be a privileged user
99 If the link named by new exists, the file's link count becomes zero
102 when it is removed, and no process has the file open, then the space
103 occupied by the file will be freed and the file will no longer be
104 accessible. If one or more processes have the file open when the last
105 link is removed, the link will be removed before rename() or renameat()
106 returns, but the removal of the file contents will be postponed until
107 all references to the file have been closed.
108 Upon successful completion, the rename() and renameat() functions will
111 mark for update the st_ctime and st_mtime fields of the parent direc‐
112 tory of each file.
113
115 Upon successful completion, 0 is returned. Otherwise, −1 is returned
116 and errno is set to indicate an error.
117
119 The rename() function will fail if:
120 EACCES A component of either path prefix denies search permis‐
122 sion; one of the directories containing old and new
123 denies write permissions; or write permission is denied
124 by a directory pointed to by old or new.
125 EBUSY The new argument is a directory and the mount point for
128 a mounted file system.
129 EDQUOT The directory where the new name entry is being placed
132 cannot be extended because the user's quota of disk
133 blocks on that file system has been exhausted.
134 EEXIST The link named by new is a directory containing entries
137 other than `.' (the directory itself) and `..' (the
138 parent directory).
139 EFAULT Either old or new references an invalid address.
142 EILSEQ The path argument includes non-UTF8 characters and the
145 file system accepts only file names where all charac‐
146 ters are part of the UTF-8 character codeset.
147 EINVAL The new argument directory pathname contains a path
150 prefix that names the old directory, or an attempt was
151 made to rename a regular file to an extended attribute
152 or from an extended attribute to a regular file.
153 EIO An I/O error occurred while making or updating a direc‐
156 tory entry.
157 EISDIR The new argument points to a directory but old points
160 to a file that is not a directory.
161 ELOOP Too many symbolic links were encountered in translating
164 the pathname.
165 ENAMETOOLONG The length of old or new exceeds PATH_MAX, or a path‐
168 name component is longer than NAME_MAX while
169 _POSIX_NO_TRUNC is in effect.
170 EMLINK The file named by old is a directory, and the link
173 count of the parent directory of new would exceed
174 LINK_MAX.
175 ENOENT The link named by old does not name an existing file, a
178 component of the path prefix of new does not exist, or
179 either old or new points to an empty string.
180 ENOSPC The directory that would contain new cannot be
183 extended.
184 ENOTDIR A component of either path prefix is not a directory,
187 or old names a directory and new names a file that is
188 not a directory, or tofd and dirfd in renameat() do not
189 reference a directory.
190 EROFS The requested operation requires writing in a directory
193 on a read-only file system.
194 EXDEV The links named by old and new are on different file
197 systems.
198 The renameat() functions will fail if:
202 ENOTSUP An attempt was made to rename a regular file as an attribute
204 file or to rename an attribute file as a regular file.
205
208 See attributes(5) for descriptions of the following attributes:
209 ┌─────────────────────────────┬────────────────────────────────┐
214 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
215 ├─────────────────────────────┼────────────────────────────────┤
216 │Interface Stability │Committed │
217 ├─────────────────────────────┼────────────────────────────────┤
218 │MT-Level │Async-Signal-Safe │
219 ├─────────────────────────────┼────────────────────────────────┤
220 │Standard │For rename(), see standards(5). │
221 └─────────────────────────────┴────────────────────────────────┘
222
224 chmod(2), link(2), unlink(2), attributes(5), fsattr(5), standards(5)
225
227 The system can deadlock if there is a loop in the file system graph.
228 Such a loop can occur if there is an entry in directory a, a/name1,
229 that is a hard link to directory b, and an entry in directory b,
230 b/name2, that is a hard link to directory a. When such a loop exists
231 and two separate processes attempt to rename a/name1 to b/name2 and
232 b/name2 to a/name1, the system may deadlock attempting to lock both
233 directories for modification. Use symbolic links instead of hard links
234 for directories.
235SunOS 5.11 4 Oct 2007 rename(2)