1RENAME(3P)                 POSIX Programmer's Manual                RENAME(3P)
2
3
4

PROLOG

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

NAME

12       rename, renameat — rename file
13

SYNOPSIS

15       #include <stdio.h>
16
17       int rename(const char *old, const char *new);
18
19       #include <fcntl.h>
20
21       int renameat(int oldfd, const char *old, int newfd,
22           const char *new);
23

DESCRIPTION

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
30       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
38       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
45       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
54       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
63       If either pathname argument refers to a path whose final  component  is
64       either dot or dot-dot, rename() shall fail.
65
66       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
70       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
77       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
85       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
89       If the rename() function fails for any reason  other  than  [EIO],  any
90       file named by new shall be unaffected.
91
92       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
104       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

RETURN VALUE

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
114       Upon successful completion, the renameat()  function  shall  return  0.
115       Otherwise, it shall return -1 and set errno to indicate the error.
116

ERRORS

118       The rename() and renameat() functions shall fail if:
119
120       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
125       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
129       [EEXIST] or [ENOTEMPTY]
130                   The link named by new is a directory that is not  an  empty
131                   directory.
132
133       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
137       EIO         A physical I/O error has occurred.
138
139       EISDIR      The new argument points to a directory and the old argument
140                   points to a file that is not a directory.
141
142       ELOOP       A loop exists in symbolic links encountered during  resolu‐
143                   tion of the path argument.
144
145       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
148       ENAMETOOLONG
149                   The length of a component of  a  pathname  is  longer  than
150                   {NAME_MAX}.
151
152       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
156       ENOSPC      The directory that would contain new cannot be extended.
157
158       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
174       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
185       EROFS       The  requested operation requires writing in a directory on
186                   a read-only file system.
187
188       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
192       In addition, the renameat() function shall fail if:
193
194       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
199       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
205       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
210       The rename() and renameat() functions may fail if:
211
212       EBUSY  The file named by the old or new arguments is a named STREAM.
213
214       ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
215              resolution of the path argument.
216
217       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
222       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
226       The following sections are informative.
227

EXAMPLES

229   Renaming a File
230       The  following  example shows how to rename a file named /home/cnd/mod1
231       to /home/cnd/mod2.
232
233
234           #include <stdio.h>
235
236           int status;
237           ...
238           status = rename("/home/cnd/mod1", "/home/cnd/mod2");
239

APPLICATION USAGE

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

RATIONALE

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
254       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
259       The  specification  that  if  old  and  new  refer  to the same file is
260       intended to guarantee that:
261
262
263           rename("x", "x");
264
265       does not remove the file.
266
267       Renaming dot or dot-dot is prohibited in order to prevent cyclical file
268       system paths.
269
270       See  also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in rmdir()
271       and [EBUSY] in unlink().  For a discussion of [EXDEV], see link().
272
273       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

FUTURE DIRECTIONS

282       None.
283

SEE ALSO

285       link(), rmdir(), symlink(), unlink()
286
287       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
301       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 .
305
306
307
308IEEE/The Open Group                  2017                           RENAME(3P)
Impressum