1RENAME(3P) POSIX Programmer's Manual RENAME(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 rename, renameat — rename file
13
15 #include <stdio.h>
16 int rename(const char *old, const char *new);
18 #include <fcntl.h>
20 int renameat(int oldfd, const char *old, int newfd,
22 const char *new);
23
25 For rename(): The functionality described on this reference page is
26 aligned with the ISO C standard. Any conflict between the requirements
27 described here and the ISO C standard is unintentional. This volume of
28 POSIX.1‐2017 defers to the ISO C standard.
29 The rename() function shall change the name of a file. The old argument
31 points to the pathname of the file to be renamed. The new argument
32 points to the new pathname of the file. If the new argument does not
33 resolve to an existing directory entry for a file of type directory and
34 the new argument contains at least one non-<slash> character and ends
35 with one or more trailing <slash> characters after all symbolic links
36 have been processed, rename() shall fail.
37 If either the old or new argument names a symbolic link, rename() shall
39 operate on the symbolic link itself, and shall not resolve the last
40 component of the argument. If the old argument and the new argument
41 resolve to either the same existing directory entry or different direc‐
42 tory entries for the same existing file, rename() shall return success‐
43 fully and perform no other action.
44 If the old argument points to the pathname of a file that is not a
46 directory, the new argument shall not point to the pathname of a direc‐
47 tory. If the link named by the new argument exists, it shall be removed
48 and old renamed to new. In this case, a link named new shall remain
49 visible to other threads throughout the renaming operation and refer
50 either to the file referred to by new or old before the operation
51 began. Write access permission is required for both the directory con‐
52 taining old and the directory containing new.
53 If the old argument points to the pathname of a directory, the new
55 argument shall not point to the pathname of a file that is not a direc‐
56 tory. If the directory named by the new argument exists, it shall be
57 removed and old renamed to new. In this case, a link named new shall
58 exist throughout the renaming operation and shall refer either to the
59 directory referred to by new or old before the operation began. If new
60 names an existing directory, it shall be required to be an empty direc‐
61 tory.
62 If either pathname argument refers to a path whose final component is
64 either dot or dot-dot, rename() shall fail.
65 If the old argument points to a pathname of a symbolic link, the sym‐
67 bolic link shall be renamed. If the new argument points to a pathname
68 of a symbolic link, the symbolic link shall be removed.
69 The old pathname shall not name an ancestor directory of the new path‐
71 name. Write access permission is required for the directory containing
72 old and the directory containing new. If the old argument points to
73 the pathname of a directory, write access permission may be required
74 for the directory named by old, and, if it exists, the directory named
75 by new.
76 If the link named by the new argument exists and the file's link count
78 becomes 0 when it is removed and no process has the file open, the
79 space occupied by the file shall be freed and the file shall no longer
80 be accessible. If one or more processes have the file open when the
81 last link is removed, the link shall be removed before rename()
82 returns, but the removal of the file contents shall be postponed until
83 all references to the file are closed.
84 Upon successful completion, rename() shall mark for update the last
86 data modification and last file status change timestamps of the parent
87 directory of each file.
88 If the rename() function fails for any reason other than [EIO], any
90 file named by new shall be unaffected.
91 The renameat() function shall be equivalent to the rename() function
93 except in the case where either old or new specifies a relative path.
94 If old is a relative path, the file to be renamed is located relative
95 to the directory associated with the file descriptor oldfd instead of
96 the current working directory. If new is a relative path, the same hap‐
97 pens only relative to the directory associated with newfd. If the
98 access mode of the open file description associated with the file
99 descriptor is not O_SEARCH, the function shall check whether directory
100 searches are permitted using the current permissions of the directory
101 underlying the file descriptor. If the access mode is O_SEARCH, the
102 function shall not perform the check.
103 If renameat() is passed the special value AT_FDCWD in the oldfd or
105 newfd parameter, the current working directory shall be used in the
106 determination of the file for the respective path parameter.
107
109 Upon successful completion, the rename() function shall return 0. Oth‐
110 erwise, it shall return -1, errno shall be set to indicate the error,
111 and neither the file named by old nor the file named by new shall be
112 changed or created.
113 Upon successful completion, the renameat() function shall return 0.
115 Otherwise, it shall return -1 and set errno to indicate the error.
116
118 The rename() and renameat() functions shall fail if:
119 EACCES A component of either path prefix denies search permission; or
121 one of the directories containing old or new denies write per‐
122 missions; or, write permission is required and is denied for a
123 directory pointed to by the old or new arguments.
124 EBUSY The directory named by old or new is currently in use by the
126 system or another process, and the implementation considers this
127 an error.
128 [EEXIST] or [ENOTEMPTY]
130 The link named by new is a directory that is not an empty
131 directory.
132 EINVAL The old pathname names an ancestor directory of the new
134 pathname, or either pathname argument contains a final com‐
135 ponent that is dot or dot-dot.
136 EIO A physical I/O error has occurred.
138 EISDIR The new argument points to a directory and the old argument
140 points to a file that is not a directory.
141 ELOOP A loop exists in symbolic links encountered during resolu‐
143 tion of the path argument.
144 EMLINK The file named by old is a directory, and the link count of
146 the parent directory of new would exceed {LINK_MAX}.
147 ENAMETOOLONG
149 The length of a component of a pathname is longer than
150 {NAME_MAX}.
151 ENOENT The link named by old does not name an existing file, a
153 component of the path prefix of new does not exist, or
154 either old or new points to an empty string.
155 ENOSPC The directory that would contain new cannot be extended.
157 ENOTDIR A component of either path prefix names an existing file
159 that is neither a directory nor a symbolic link to a direc‐
160 tory; or the old argument names a directory and the new
161 argument names a non-directory file; or the old argument
162 contains at least one non-<slash> character and ends with
163 one or more trailing <slash> characters and the last path‐
164 name component names an existing file that is neither a
165 directory nor a symbolic link to a directory; or the old
166 argument names an existing non-directory file and the new
167 argument names a nonexistent file, contains at least one
168 non-<slash> character, and ends with one or more trailing
169 <slash> characters; or the new argument names an existing
170 non-directory file, contains at least one non-<slash> char‐
171 acter, and ends with one or more trailing <slash> charac‐
172 ters.
173 EPERM or EACCES
175 The S_ISVTX flag is set on the directory containing the
176 file referred to by old and the process does not satisfy
177 the criteria specified in the Base Definitions volume of
178 POSIX.1‐2017, Section 4.3, Directory Protection with
179 respect to old; or new refers to an existing file, the
180 S_ISVTX flag is set on the directory containing this file,
181 and the process does not satisfy the criteria specified in
182 the Base Definitions volume of POSIX.1‐2017, Section 4.3,
183 Directory Protection with respect to this file.
184 EROFS The requested operation requires writing in a directory on
186 a read-only file system.
187 EXDEV The links named by new and old are on different file sys‐
189 tems and the implementation does not support links between
190 file systems.
191 In addition, the renameat() function shall fail if:
193 EACCES The access mode of the open file description associated with
195 oldfd or newfd is not O_SEARCH and the permissions of the direc‐
196 tory underlying oldfd or newfd, respectively, do not permit
197 directory searches.
198 EBADF The old argument does not specify an absolute path and the oldfd
200 argument is neither AT_FDCWD nor a valid file descriptor open
201 for reading or searching, or the new argument does not specify
202 an absolute path and the newfd argument is neither AT_FDCWD nor
203 a valid file descriptor open for reading or searching.
204 ENOTDIR
206 The old or new argument is not an absolute path and oldfd or
207 newfd, respectively, is a file descriptor associated with a non-
208 directory file.
209 The rename() and renameat() functions may fail if:
211 EBUSY The file named by the old or new arguments is a named STREAM.
213 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
215 resolution of the path argument.
216 ENAMETOOLONG
218 The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
219 tion of a symbolic link produced an intermediate result with a
220 length that exceeds {PATH_MAX}.
221 ETXTBSY
223 The file named by new exists and is the last directory entry to
224 a pure procedure (shared text) file that is being executed.
225 The following sections are informative.
227
229 Renaming a File
230 The following example shows how to rename a file named /home/cnd/mod1
231 to /home/cnd/mod2.
232 #include <stdio.h>
235 int status;
237 ...
238 status = rename("/home/cnd/mod1", "/home/cnd/mod2");
239
241 Some implementations mark for update the last file status change time‐
242 stamp of renamed files and some do not. Applications which make use of
243 the last file status change timestamp may behave differently with
244 respect to renamed files unless they are designed to allow for either
245 behavior.
246
248 This rename() function is equivalent for regular files to that defined
249 by the ISO C standard. Its inclusion here expands that definition to
250 include actions on directories and specifies behavior when the new
251 parameter names a file that already exists. That specification requires
252 that the action of the function be atomic.
253 One of the reasons for introducing this function was to have a means of
255 renaming directories while permitting implementations to prohibit the
256 use of link() and unlink() with directories, thus constraining links to
257 directories to those made by mkdir().
258 The specification that if old and new refer to the same file is
260 intended to guarantee that:
261 rename("x", "x");
264 does not remove the file.
266 Renaming dot or dot-dot is prohibited in order to prevent cyclical file
268 system paths.
269 See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in rmdir()
271 and [EBUSY] in unlink(). For a discussion of [EXDEV], see link().
272 The purpose of the renameat() function is to rename files in directo‐
274 ries other than the current working directory without exposure to race
275 conditions. Any part of the path of a file could be changed in parallel
276 to a call to rename(), resulting in unspecified behavior. By opening
277 file descriptors for the source and target directories and using the
278 renameat() function it can be guaranteed that that renamed file is
279 located correctly and the resulting file is in the desired directory.
280
282 None.
283
285 link(), rmdir(), symlink(), unlink()
286 The Base Definitions volume of POSIX.1‐2017, Section 4.3, Directory
288 Protection, <fcntl.h>, <stdio.h>
289
291 Portions of this text are reprinted and reproduced in electronic form
292 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
293 table Operating System Interface (POSIX), The Open Group Base Specifi‐
294 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
295 Electrical and Electronics Engineers, Inc and The Open Group. In the
296 event of any discrepancy between this version and the original IEEE and
297 The Open Group Standard, the original IEEE and The Open Group Standard
298 is the referee document. The original Standard can be obtained online
299 at http://www.opengroup.org/unix/online.html .
300 Any typographical or formatting errors that appear in this page are
302 most likely to have been introduced during the conversion of the source
303 files to man page format. To report such errors, see https://www.ker‐
304 nel.org/doc/man-pages/reporting_bugs.html .
305IEEE/The Open Group 2017 RENAME(3P)