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