| .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
| .\" and Copyright (C) 1993 Michael Haardt; |
| .\" and Copyright (C) 1993,1995 Ian Jackson |
| .\" and Copyright (C) 2006, 2014 Michael Kerrisk |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified Sat Jul 24 00:35:52 1993 by Rik Faith <faith@cs.unc.edu> |
| .\" Modified Thu Jun 4 12:21:13 1998 by Andries Brouwer <aeb@cwi.nl> |
| .\" Modified Thu Mar 3 09:49:35 2005 by Michael Haardt <michael@moria.de> |
| .\" 2007-03-25, mtk, added various text to DESCRIPTION. |
| .\" |
| .TH RENAME 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| rename, renameat, renameat2 \- change the name or location of a file |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdio.h> |
| .PP |
| .BI "int rename(const char *" oldpath ", const char *" newpath ); |
| .PP |
| .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
| .B #include <stdio.h> |
| .PP |
| .BI "int renameat(int " olddirfd ", const char *" oldpath , |
| .BI " int " newdirfd ", const char *" newpath ); |
| .BI "int renameat2(int " olddirfd ", const char *" oldpath , |
| .BI " int " newdirfd ", const char *" newpath \ |
| ", unsigned int " flags ); |
| .fi |
| .PP |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .PP |
| .nf |
| .BR renameat (): |
| Since glibc 2.10: |
| _POSIX_C_SOURCE >= 200809L |
| Before glibc 2.10: |
| _ATFILE_SOURCE |
| .PP |
| .BR renameat2 (): |
| _GNU_SOURCE |
| .fi |
| .SH DESCRIPTION |
| .BR rename () |
| renames a file, moving it between directories if required. |
| Any other hard links to the file (as created using |
| .BR link (2)) |
| are unaffected. |
| Open file descriptors for |
| .I oldpath |
| are also unaffected. |
| .PP |
| Various restrictions determine whether or not the rename operation succeeds: |
| see ERRORS below. |
| .PP |
| If |
| .I newpath |
| already exists, it will be atomically replaced, so that there is |
| no point at which another process attempting to access |
| .I newpath |
| will find it missing. |
| However, there will probably be a window in which both |
| .I oldpath |
| and |
| .I newpath |
| refer to the file being renamed. |
| .PP |
| If |
| .I oldpath |
| and |
| .I newpath |
| are existing hard links referring to the same file, then |
| .BR rename () |
| does nothing, and returns a success status. |
| .PP |
| If |
| .I newpath |
| exists but the operation fails for some reason, |
| .BR rename () |
| guarantees to leave an instance of |
| .I newpath |
| in place. |
| .PP |
| .I oldpath |
| can specify a directory. |
| In this case, |
| .I newpath |
| must either not exist, or it must specify an empty directory. |
| .PP |
| If |
| .I oldpath |
| refers to a symbolic link, the link is renamed; if |
| .I newpath |
| refers to a symbolic link, the link will be overwritten. |
| .SS renameat() |
| The |
| .BR renameat () |
| system call operates in exactly the same way as |
| .BR rename (), |
| except for the differences described here. |
| .PP |
| If the pathname given in |
| .I oldpath |
| is relative, then it is interpreted relative to the directory |
| referred to by the file descriptor |
| .I olddirfd |
| (rather than relative to the current working directory of |
| the calling process, as is done by |
| .BR rename () |
| for a relative pathname). |
| .PP |
| If |
| .I oldpath |
| is relative and |
| .I olddirfd |
| is the special value |
| .BR AT_FDCWD , |
| then |
| .I oldpath |
| is interpreted relative to the current working |
| directory of the calling process (like |
| .BR rename ()). |
| .PP |
| If |
| .I oldpath |
| is absolute, then |
| .I olddirfd |
| is ignored. |
| .PP |
| The interpretation of |
| .I newpath |
| is as for |
| .IR oldpath , |
| except that a relative pathname is interpreted relative |
| to the directory referred to by the file descriptor |
| .IR newdirfd . |
| .PP |
| See |
| .BR openat (2) |
| for an explanation of the need for |
| .BR renameat (). |
| .SS renameat2() |
| .BR renameat2 () |
| has an additional |
| .I flags |
| argument. |
| A |
| .BR renameat2 () |
| call with a zero |
| .I flags |
| argument is equivalent to |
| .BR renameat (). |
| .PP |
| The |
| .I flags |
| argument is a bit mask consisting of zero or more of the following flags: |
| .TP |
| .B RENAME_EXCHANGE |
| Atomically exchange |
| .IR oldpath |
| and |
| .IR newpath . |
| Both pathnames must exist |
| but may be of different types (e.g., one could be a non-empty directory |
| and the other a symbolic link). |
| .TP |
| .B RENAME_NOREPLACE |
| Don't overwrite |
| .IR newpath |
| of the rename. |
| Return an error if |
| .IR newpath |
| already exists. |
| .IP |
| .B RENAME_NOREPLACE |
| can't be employed together with |
| .BR RENAME_EXCHANGE . |
| .IP |
| .B RENAME_NOREPLACE |
| requires support from the underlying filesystem. |
| Support for various filesystems was added as follows: |
| .RS |
| .IP * 3 |
| ext4 (Linux 3.15); |
| .\" ext4: commit 0a7c3937a1f23f8cb5fc77ae01661e9968a51d0c |
| .IP * |
| btrfs, tmpfs, and cifs (Linux 3.17); |
| .IP * |
| xfs (Linux 4.0); |
| .\" btrfs: commit 80ace85c915d0f41016f82917218997b72431258 |
| .\" tmpfs: commit 3b69ff51d087d265aa4af3a532fc4f20bf33e718 |
| .\" cifs: commit 7c33d5972ce382bcc506d16235f1e9b7d22cbef8 |
| .\" |
| .\" gfs2 in 4.2? |
| .IP * |
| Support for many other filesystems was added in Linux 4.9, including |
| ext2, minix, reiserfs, jfs, vfat, and bpf. |
| .\" Also affs, bfs, exofs, hfs, hfsplus, jffs2, logfs, msdos, |
| .\" nilfs2, omfs, sysvfs, ubifs, udf, ufs |
| .\" hugetlbfs, ramfs |
| .\" local filesystems: commit f03b8ad8d38634d13e802165cc15917481b47835 |
| .\" libfs: commit e0e0be8a835520e2f7c89f214dfda570922a1b90 |
| .RE |
| .TP |
| .BR RENAME_WHITEOUT " (since Linux 3.18)" |
| .\" commit 0d7a855526dd672e114aff2ac22b60fc6f155b08 |
| .\" commit 787fb6bc9682ec7c05fb5d9561b57100fbc1cc41 |
| This operation makes sense only for overlay/union |
| filesystem implementations. |
| .IP |
| Specifying |
| .B RENAME_WHITEOUT |
| creates a "whiteout" object at the source of |
| the rename at the same time as performing the rename. |
| The whole operation is atomic, |
| so that if the rename succeeds then the whiteout will also have been created. |
| .IP |
| A "whiteout" is an object that has special meaning in union/overlay |
| filesystem constructs. |
| In these constructs, |
| multiple layers exist and only the top one is ever modified. |
| A whiteout on an upper layer will effectively hide a |
| matching file in the lower layer, |
| making it appear as if the file didn't exist. |
| .IP |
| When a file that exists on the lower layer is renamed, |
| the file is first copied up (if not already on the upper layer) |
| and then renamed on the upper, read-write layer. |
| At the same time, the source file needs to be "whiteouted" |
| (so that the version of the source file in the lower layer |
| is rendered invisible). |
| The whole operation needs to be done atomically. |
| .IP |
| When not part of a union/overlay, |
| the whiteout appears as a character device with a {0,0} device number. |
| .\" https://www.freebsd.org/cgi/man.cgi?query=mount_unionfs&manpath=FreeBSD+11.0-RELEASE |
| (Note that other union/overlay implementations may employ different methods |
| for storing whiteout entries; specifically, BSD union mount employs |
| a separate inode type, |
| .BR DT_WHT , |
| which, while supported by some filesystems available in Linux, |
| such as CODA and XFS, is ignored by the kernel's whiteout support code, |
| as of Linux 4.19, at least.) |
| .IP |
| .B RENAME_WHITEOUT |
| requires the same privileges as creating a device node (i.e., the |
| .BR CAP_MKNOD |
| capability). |
| .IP |
| .B RENAME_WHITEOUT |
| can't be employed together with |
| .BR RENAME_EXCHANGE . |
| .IP |
| .B RENAME_WHITEOUT |
| requires support from the underlying filesystem. |
| Among the filesystems that support it are |
| tmpfs (since Linux 3.18), |
| .\" tmpfs: commit 46fdb794e3f52ef18b859ebc92f0a9d7db21c5df |
| ext4 (since Linux 3.18), |
| .\" ext4: commit cd808deced431b66b5fa4e5c193cb7ec0059eaff |
| XFS (since Linux 4.1), |
| .\" XFS: commit 7dcf5c3e4527cfa2807567b00387cf2ed5e07f00 |
| f2fs (since Linux 4.2), |
| .\" f2fs: commit 7e01e7ad746bc8198a8b46163ddc73a1c7d22339 |
| btrfs (since Linux 4.7), |
| .\" btrfs: commit cdd1fedf8261cd7a73c0596298902ff4f0f04492 |
| and ubifs (since Linux 4.9). |
| .\" ubifs: commit 9e0a1fff8db56eaaebb74b4a3ef65f86811c4798 |
| .SH RETURN VALUE |
| On success, zero is returned. |
| On error, \-1 is returned, and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EACCES |
| Write permission is denied for the directory containing |
| .I oldpath |
| or |
| .IR newpath , |
| or, search permission is denied for one of the directories |
| in the path prefix of |
| .I oldpath |
| or |
| .IR newpath , |
| or |
| .I oldpath |
| is a directory and does not allow write permission (needed to update |
| the |
| .I .. |
| entry). |
| (See also |
| .BR path_resolution (7).) |
| .TP |
| .B EBUSY |
| The rename fails because |
| .IR oldpath " or " newpath |
| is a directory that is in use by some process (perhaps as |
| current working directory, or as root directory, or because |
| it was open for reading) or is in use by the system |
| (for example as mount point), while the system considers |
| this an error. |
| (Note that there is no requirement to return |
| .B EBUSY |
| in such |
| cases\(emthere is nothing wrong with doing the rename anyway\(embut |
| it is allowed to return |
| .B EBUSY |
| if the system cannot otherwise |
| handle such situations.) |
| .TP |
| .B EDQUOT |
| The user's quota of disk blocks on the filesystem has been exhausted. |
| .TP |
| .B EFAULT |
| .IR oldpath " or " newpath " points outside your accessible address space." |
| .TP |
| .B EINVAL |
| The new pathname contained a path prefix of the old, or, more generally, |
| an attempt was made to make a directory a subdirectory of itself. |
| .TP |
| .B EISDIR |
| .I newpath |
| is an existing directory, but |
| .I oldpath |
| is not a directory. |
| .TP |
| .B ELOOP |
| Too many symbolic links were encountered in resolving |
| .IR oldpath " or " newpath . |
| .TP |
| .B EMLINK |
| .I oldpath |
| already has the maximum number of links to it, or |
| it was a directory and the directory containing |
| .I newpath |
| has the maximum number of links. |
| .TP |
| .B ENAMETOOLONG |
| .IR oldpath " or " newpath " was too long." |
| .TP |
| .B ENOENT |
| The link named by |
| .I oldpath |
| does not exist; |
| or, a directory component in |
| .I newpath |
| does not exist; |
| or, |
| .I oldpath |
| or |
| .I newpath |
| is an empty string. |
| .TP |
| .B ENOMEM |
| Insufficient kernel memory was available. |
| .TP |
| .B ENOSPC |
| The device containing the file has no room for the new directory |
| entry. |
| .TP |
| .B ENOTDIR |
| A component used as a directory in |
| .IR oldpath " or " newpath |
| is not, in fact, a directory. |
| Or, |
| .I oldpath |
| is a directory, and |
| .I newpath |
| exists but is not a directory. |
| .TP |
| .BR ENOTEMPTY " or " EEXIST |
| .I newpath |
| is a nonempty directory, that is, contains entries other than "." and "..". |
| .TP |
| .BR EPERM " or " EACCES |
| The directory containing |
| .I oldpath |
| has the sticky bit |
| .RB ( S_ISVTX ) |
| set and the process's effective user ID is neither |
| the user ID of the file to be deleted nor that of the directory |
| containing it, and the process is not privileged |
| (Linux: does not have the |
| .B CAP_FOWNER |
| capability); |
| or |
| .I newpath |
| is an existing file and the directory containing it has the sticky bit set |
| and the process's effective user ID is neither the user ID of the file |
| to be replaced nor that of the directory containing it, |
| and the process is not privileged |
| (Linux: does not have the |
| .B CAP_FOWNER |
| capability); |
| or the filesystem containing |
| .I pathname |
| does not support renaming of the type requested. |
| .TP |
| .B EROFS |
| The file is on a read-only filesystem. |
| .TP |
| .B EXDEV |
| .IR oldpath " and " newpath |
| are not on the same mounted filesystem. |
| (Linux permits a filesystem to be mounted at multiple points, but |
| .BR rename () |
| does not work across different mount points, |
| even if the same filesystem is mounted on both.) |
| .PP |
| The following additional errors can occur for |
| .BR renameat () |
| and |
| .BR renameat2 (): |
| .TP |
| .B EBADF |
| .I olddirfd |
| or |
| .I newdirfd |
| is not a valid file descriptor. |
| .TP |
| .B ENOTDIR |
| .I oldpath |
| is relative and |
| .I olddirfd |
| is a file descriptor referring to a file other than a directory; |
| or similar for |
| .I newpath |
| and |
| .I newdirfd |
| .PP |
| The following additional errors can occur for |
| .BR renameat2 (): |
| .TP |
| .B EEXIST |
| .I flags |
| contains |
| .B RENAME_NOREPLACE |
| and |
| .I newpath |
| already exists. |
| .TP |
| .B EINVAL |
| An invalid flag was specified in |
| .IR flags . |
| .TP |
| .B EINVAL |
| Both |
| .B RENAME_NOREPLACE |
| and |
| .B RENAME_EXCHANGE |
| were specified in |
| .IR flags . |
| .TP |
| .B EINVAL |
| Both |
| .B RENAME_WHITEOUT |
| and |
| .B RENAME_EXCHANGE |
| were specified in |
| .IR flags . |
| .TP |
| .B EINVAL |
| The filesystem does not support one of the flags in |
| .IR flags . |
| .TP |
| .B ENOENT |
| .I flags |
| contains |
| .B RENAME_EXCHANGE |
| and |
| .IR newpath |
| does not exist. |
| .TP |
| .B EPERM |
| .B RENAME_WHITEOUT |
| was specified in |
| .IR flags , |
| but the caller does not have the |
| .B CAP_MKNOD |
| capability. |
| .SH VERSIONS |
| .BR renameat () |
| was added to Linux in kernel 2.6.16; |
| library support was added to glibc in version 2.4. |
| .PP |
| .BR renameat2 () |
| was added to Linux in kernel 3.15; library support was added in glibc 2.28. |
| .SH CONFORMING TO |
| .BR rename (): |
| 4.3BSD, C89, C99, POSIX.1-2001, POSIX.1-2008. |
| .PP |
| .BR renameat (): |
| POSIX.1-2008. |
| .PP |
| .BR renameat2 () |
| is Linux-specific. |
| .SH NOTES |
| .\" |
| .SS Glibc notes |
| On older kernels where |
| .BR renameat () |
| is unavailable, the glibc wrapper function falls back to the use of |
| .BR rename (). |
| When |
| .I oldpath |
| and |
| .I newpath |
| are relative pathnames, |
| glibc constructs pathnames based on the symbolic links in |
| .IR /proc/self/fd |
| that correspond to the |
| .I olddirfd |
| and |
| .IR newdirfd |
| arguments. |
| .SH BUGS |
| On NFS filesystems, you can not assume that if the operation |
| failed, the file was not renamed. |
| If the server does the rename operation |
| and then crashes, the retransmitted RPC which will be processed when the |
| server is up again causes a failure. |
| The application is expected to |
| deal with this. |
| See |
| .BR link (2) |
| for a similar problem. |
| .SH SEE ALSO |
| .BR mv (1), |
| .BR rename (1), |
| .BR chmod (2), |
| .BR link (2), |
| .BR symlink (2), |
| .BR unlink (2), |
| .BR path_resolution (7), |
| .BR symlink (7) |