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 - rename a file
13
15 #include <stdio.h>
16 int rename(const char *old, const char *new);
18
21 The rename() function shall change the name of a file. The old argument
22 points to the pathname of the file to be renamed. The new argument
23 points to the new pathname of the file.
24 If either the old or new argument names a symbolic link, rename() shall
26 operate on the symbolic link itself, and shall not resolve the last
27 component of the argument. If the old argument and the new argument
28 resolve to the same existing file, rename() shall return successfully
29 and perform no other action.
30 If the old argument points to the pathname of a file that is not a
32 directory, the new argument shall not point to the pathname of a direc‐
33 tory. If the link named by the new argument exists, it shall be removed
34 and old renamed to new. In this case, a link named new shall remain
35 visible to other processes throughout the renaming operation and refer
36 either to the file referred to by new or old before the operation
37 began. Write access permission is required for both the directory con‐
38 taining old and the directory containing new.
39 If the old argument points to the pathname of a directory, the new
41 argument shall not point to the pathname of a file that is not a direc‐
42 tory. If the directory named by the new argument exists, it shall be
43 removed and old renamed to new. In this case, a link named new shall
44 exist throughout the renaming operation and shall refer either to the
45 directory referred to by new or old before the operation began. If new
46 names an existing directory, it shall be required to be an empty direc‐
47 tory.
48 If the old argument points to a pathname of a symbolic link, the sym‐
50 bolic link shall be renamed. If the new argument points to a pathname
51 of a symbolic link, the symbolic link shall be removed.
52 The new pathname shall not contain a path prefix that names old. Write
54 access permission is required for the directory containing old and the
55 directory containing new. If the old argument points to the pathname
56 of a directory, write access permission may be required for the direc‐
57 tory named by old, and, if it exists, the directory named by new.
58 If the link named by the new argument exists and the file's link count
60 becomes 0 when it is removed and no process has the file open, the
61 space occupied by the file shall be freed and the file shall no longer
62 be accessible. If one or more processes have the file open when the
63 last link is removed, the link shall be removed before rename()
64 returns, but the removal of the file contents shall be postponed until
65 all references to the file are closed.
66 Upon successful completion, rename() shall mark for update the st_ctime
68 and st_mtime fields of the parent directory of each file.
69 If the rename() function fails for any reason other than [EIO], any
71 file named by new shall be unaffected.
72
74 Upon successful completion, rename() shall return 0; otherwise, -1
75 shall be returned, errno shall be set to indicate the error, and
76 neither the file named by old nor the file named by new shall be
77 changed or created.
78
80 The rename() function shall fail if:
81 EACCES A component of either path prefix denies search permission; or
83 one of the directories containing old or new denies write per‐
84 missions; or, write permission is required and is denied for a
85 directory pointed to by the old or new arguments.
86 EBUSY The directory named by old or new is currently in use by the
88 system or another process, and the implementation considers this
89 an error.
90 EEXIST or ENOTEMPTY
92 The link named by new is a directory that is not an empty direc‐
94 tory.
95 EINVAL The new directory pathname contains a path prefix that names the
97 old directory.
98 EIO A physical I/O error has occurred.
100 EISDIR The new argument points to a directory and the old argument
102 points to a file that is not a directory.
103 ELOOP A loop exists in symbolic links encountered during resolution of
105 the path argument.
106 EMLINK The file named by old is a directory, and the link count of the
108 parent directory of new would exceed {LINK_MAX}.
109 ENAMETOOLONG
111 The length of the old or new argument exceeds {PATH_MAX} or a
113 pathname component is longer than {NAME_MAX}.
114 ENOENT The link named by old does not name an existing file, or either
116 old or new points to an empty string.
117 ENOSPC The directory that would contain new cannot be extended.
119 ENOTDIR
121 A component of either path prefix is not a directory; or the old
122 argument names a directory and new argument names a non-direc‐
123 tory file.
124 EPERM or EACCES
126 The S_ISVTX flag is set on the directory containing the file
128 referred to by old and the caller is not the file owner, nor is
129 the caller the directory owner, nor does the caller have appro‐
130 priate privileges; or new refers to an existing file, the
131 S_ISVTX flag is set on the directory containing this file, and
132 the caller is not the file owner, nor is the caller the direc‐
133 tory owner, nor does the caller have appropriate privileges.
134 EROFS The requested operation requires writing in a directory on a
136 read-only file system.
137 EXDEV The links named by new and old are on different file systems and
139 the implementation does not support links between file systems.
140 The rename() function may fail if:
143 EBUSY The file named by the old or new arguments is a named STREAM.
145 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
147 resolution of the path argument.
148 ENAMETOOLONG
150 As a result of encountering a symbolic link in resolution of the
152 path argument, the length of the substituted pathname string
153 exceeded {PATH_MAX}.
154 ETXTBSY
156 The file to be renamed is a pure procedure (shared text) file
157 that is being executed.
158 The following sections are informative.
161
163 Renaming a File
164 The following example shows how to rename a file named /home/cnd/mod1
165 to /home/cnd/mod2.
166 #include <stdio.h>
169 int status;
172 ...
173 status = rename("/home/cnd/mod1", "/home/cnd/mod2");
174
176 Some implementations mark for update the st_ctime field of renamed
177 files and some do not. Applications which make use of the st_ctime
178 field may behave differently with respect to renamed files unless they
179 are designed to allow for either behavior.
180
182 This rename() function is equivalent for regular files to that defined
183 by the ISO C standard. Its inclusion here expands that definition to
184 include actions on directories and specifies behavior when the new
185 parameter names a file that already exists. That specification requires
186 that the action of the function be atomic.
187 One of the reasons for introducing this function was to have a means of
189 renaming directories while permitting implementations to prohibit the
190 use of link() and unlink() with directories, thus constraining links to
191 directories to those made by mkdir().
192 The specification that if old and new refer to the same file is
194 intended to guarantee that:
195 rename("x", "x");
198 does not remove the file.
200 Renaming dot or dot-dot is prohibited in order to prevent cyclical file
202 system paths.
203 See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in rmdir()
205 and [EBUSY] in unlink(). For a discussion of [EXDEV], see link() .
206
208 None.
209
211 link(), rmdir(), symlink(), unlink(), the Base Definitions volume of
212 IEEE Std 1003.1-2001, <stdio.h>
213
215 Portions of this text are reprinted and reproduced in electronic form
216 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
217 -- Portable Operating System Interface (POSIX), The Open Group Base
218 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
219 Electrical and Electronics Engineers, Inc and The Open Group. In the
220 event of any discrepancy between this version and the original IEEE and
221 The Open Group Standard, the original IEEE and The Open Group Standard
222 is the referee document. The original Standard can be obtained online
223 at http://www.opengroup.org/unix/online.html .
224IEEE/The Open Group 2003 RENAME(3P)