1rename(2)                        System Calls                        rename(2)
2
3
4

NAME

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

SYNOPSIS

9       #include <stdio.h>
10
11       int rename(const char *old, const char *new);
12
13
14       #include <unistd.h>
15
16       int renameat(int fromfd, const char *old, int tofd,
17            const char *new);
18
19
20   XPG3
21       #include <unistd.h>
22
23       int rename(const char *old, const char *new);
24
25

DESCRIPTION

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
31
32       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
42
43       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
48
49       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
52
53       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
60
61       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
69
70       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
76
77       If the directory containing old has the sticky bit set,  at  least  one
78       of the following conditions listed below must be true:
79
80           o      the user must own old
81
82           o      the user must own the directory containing old
83
84           o      old must be writable by the user
85
86           o      the user must be a privileged user
87
88
89       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
92           o      the user must own new
93
94           o      the user must own the directory containing new
95
96           o      new must be writable by the user
97
98           o      the user must be a privileged user
99
100
101       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
109
110       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

RETURN VALUES

115       Upon successful completion, 0 is returned. Otherwise,  −1  is  returned
116       and errno is set to indicate an error.
117

ERRORS

119       The rename() function will fail if:
120
121       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
126
127       EBUSY           The new argument is a directory and the mount point for
128                       a mounted file system.
129
130
131       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
135
136       EEXIST          The link named by new is a directory containing entries
137                       other than `.' (the directory  itself)  and  `..'  (the
138                       parent directory).
139
140
141       EFAULT          Either old or new references an invalid address.
142
143
144       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
148
149       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
154
155       EIO             An I/O error occurred while making or updating a direc‐
156                       tory entry.
157
158
159       EISDIR          The  new  argument points to a directory but old points
160                       to a file that is not a directory.
161
162
163       ELOOP           Too many symbolic links were encountered in translating
164                       the pathname.
165
166
167       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
171
172       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
176
177       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
181
182       ENOSPC          The   directory   that  would  contain  new  cannot  be
183                       extended.
184
185
186       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
191
192       EROFS           The requested operation requires writing in a directory
193                       on a read-only file system.
194
195
196       EXDEV           The links named by old and new are  on  different  file
197                       systems.
198
199
200
201       The renameat() functions will fail if:
202
203       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
206

ATTRIBUTES

208       See attributes(5) for descriptions of the following attributes:
209
210
211
212
213       ┌─────────────────────────────┬────────────────────────────────┐
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

SEE ALSO

224       chmod(2), link(2), unlink(2), attributes(5), fsattr(5), standards(5)
225

NOTES

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.
235
236
237
238SunOS 5.11                        4 Oct 2007                         rename(2)
Impressum