Movatterモバイル変換

rename(2) — Linux manual page

NAME \|LIBRARY \|SYNOPSIS \|DESCRIPTION \|RETURN VALUE \|ERRORS \|STANDARDS \|HISTORY \|BUGS \|SEE ALSO \|COLOPHON

rename(2)                  System Calls Manualrename(2)

NAME top

       rename, renameat, renameat2 - change the name or location of a       file

LIBRARY top

       Standard C library (libc,-lc)

SYNOPSIS top

#include <stdio.h>int rename(const char *oldpath, const char *newpath);#include <fcntl.h>/* Definition ofAT_*constants */#include <stdio.h>int renameat(intolddirfd, const char *oldpath,intnewdirfd, const char *newpath);int renameat2(intolddirfd, const char *oldpath,intnewdirfd, const char *newpath, unsigned intflags);   Feature Test Macro Requirements for glibc (seefeature_test_macros(7)):renameat():           Since glibc 2.10:               _POSIX_C_SOURCE >= 200809L           Before glibc 2.10:               _ATFILE_SOURCErenameat2():           _GNU_SOURCE

DESCRIPTION top

rename() renames a file, moving it between directories if required. Any other hard links to the file (as created usinglink(2)) are unaffected. Open file descriptors foroldpath are also unaffected. Various restrictions determine whether or not the rename operation succeeds: see ERRORS below. Ifnewpath already exists, it will be atomically replaced, so that there is no point at which another process attempting to accessnewpath will find it missing. However, there will probably be a window in which botholdpath andnewpath refer to the file being renamed. Ifoldpath andnewpath are existing hard links referring to the same file, thenrename() does nothing, and returns a success status. Ifnewpath exists but the operation fails for some reason,rename() guarantees to leave an instance ofnewpath in place.oldpath can specify a directory. In this case,newpath must either not exist, or it must specify an empty directory. Ifoldpath refers to a symbolic link, the link is renamed; ifnewpath refers to a symbolic link, the link will be overwritten.renameat() Therenameat() system call operates in exactly the same way asrename(), except for the differences described here. If the pathname given inoldpath is relative, then it is interpreted relative to the directory referred to by the file descriptorolddirfd (rather than relative to the current working directory of the calling process, as is done byrename() for a relative pathname). Ifoldpath is relative andolddirfd is the special valueAT_FDCWD, thenoldpath is interpreted relative to the current working directory of the calling process (likerename()). Ifoldpath is absolute, thenolddirfd is ignored. The interpretation ofnewpath is as foroldpath, except that a relative pathname is interpreted relative to the directory referred to by the file descriptornewdirfd. Seeopenat(2) for an explanation of the need forrenameat().renameat2()renameat2() has an additionalflags argument. Arenameat2() call with a zeroflags argument is equivalent torenameat(). Theflags argument is a bit mask consisting of zero or more of the following flags:RENAME_EXCHANGE Atomically exchangeoldpath andnewpath. 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).RENAME_NOREPLACE Don't overwritenewpath of the rename. Return an error ifnewpath already exists.RENAME_NOREPLACEcan't be employed together withRENAME_EXCHANGE.RENAME_NOREPLACErequires support from the underlying filesystem. Support for various filesystems was added as follows: • ext4 (Linux 3.15); • btrfs, tmpfs, and cifs (Linux 3.17); • xfs (Linux 4.0); • Support for many other filesystems was added in Linux 4.9, including ext2, minix, reiserfs, jfs, vfat, and bpf.RENAME_WHITEOUT(since Linux 3.18) This operation makes sense only for overlay/union filesystem implementations. SpecifyingRENAME_WHITEOUTcreates 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. 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. 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. When not part of a union/overlay, the whiteout appears as a character device with a {0,0} device number. (Note that other union/overlay implementations may employ different methods for storing whiteout entries; specifically, BSD union mount employs a separate inode type,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.)RENAME_WHITEOUTrequires the same privileges as creating a device node (i.e., theCAP_MKNODcapability).RENAME_WHITEOUTcan't be employed together withRENAME_EXCHANGE.RENAME_WHITEOUTrequires support from the underlying filesystem. Among the filesystems that support it are tmpfs (since Linux 3.18), ext4 (since Linux 3.18), XFS (since Linux 4.1), f2fs (since Linux 4.2), btrfs (since Linux 4.7), and ubifs (since Linux 4.9).

RETURN VALUE top

       On success, zero is returned.  On error, -1 is returned, anderrno       is set to indicate the error.

ERRORS top

EACCESWrite permission is denied for the directory containingoldpath ornewpath, or, search permission is denied for one              of the directories in the path prefix ofoldpath ornewpath, oroldpath is a directory and does not allow write              permission (needed to update the..  entry).  (See alsopath_resolution(7).)EBUSYThe rename fails becauseoldpath ornewpath 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 a mount              point), while the system considers this an error.  (Note              that there is no requirement to returnEBUSYin such cases—              there is nothing wrong with doing the rename anyway—but it              is allowed to returnEBUSYif the system cannot otherwise              handle such situations.)EDQUOTThe user's quota of disk blocks on the filesystem has been              exhausted.EFAULToldpath ornewpath points outside your accessible address              space.EINVALThe new pathname contained a path prefix of the old, or,              more generally, an attempt was made to make a directory a              subdirectory of itself.EISDIRnewpath is an existing directory, butoldpath is not a              directory.ELOOPToo many symbolic links were encountered in resolvingoldpath ornewpath.EMLINKoldpath already has the maximum number of links to it, or              it was a directory and the directory containingnewpath has              the maximum number of links.ENAMETOOLONGoldpath ornewpath was too long.ENOENTThe link named byoldpath does not exist; or, a directory              component innewpath does not exist; or,oldpath ornewpath              is an empty string.ENOMEMInsufficient kernel memory was available.ENOSPCThe device containing the file has no room for the new              directory entry.ENOTDIR              A component used as a directory inoldpath ornewpath is              not, in fact, a directory.  Or,oldpath is a directory, andnewpath exists but is not a directory.ENOTEMPTYorEEXISTnewpath is a nonempty directory, that is, contains entries              other than "." and "..".EPERMorEACCES              The directory containingoldpath has the sticky bit              (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 theCAP_FOWNER              capability); ornewpath 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              theCAP_FOWNERcapability); or the filesystem containingoldpath does not support renaming of the type requested.EROFSThe file is on a read-only filesystem.EXDEVoldpath andnewpath are not on the same mounted filesystem.              (Linux permits a filesystem to be mounted at multiple              points, butrename() does not work across different mount              points, even if the same filesystem is mounted on both.)       The following additional errors can occur forrenameat() andrenameat2():EBADFoldpath (newpath) is relative butolddirfd (newdirfd) is              not a valid file descriptor.ENOTDIRoldpath is relative andolddirfd is a file descriptor              referring to a file other than a directory; or similar fornewpath andnewdirfd       The following additional errors can occur forrenameat2():EEXISTflags containsRENAME_NOREPLACEandnewpath already exists.EINVALAn invalid flag was specified inflags.EINVALBothRENAME_NOREPLACEandRENAME_EXCHANGEwere specified inflags.EINVALBothRENAME_WHITEOUTandRENAME_EXCHANGEwere specified inflags.EINVALThe filesystem does not support one of the flags inflags.ENOENTflags containsRENAME_EXCHANGEandnewpath does not exist.EPERM  RENAME_WHITEOUTwas specified inflags, but the caller does              not have theCAP_MKNODcapability.

STANDARDS top

rename()              C11, POSIX.1-2008.renameat()              POSIX.1-2008.renameat2()              Linux.

HISTORY top

rename()              4.3BSD, C89, POSIX.1-2001.renameat()              Linux 2.6.16, glibc 2.4.renameat2()              Linux 3.15, glibc 2.28.glibc notes       On older kernels whererenameat() is unavailable, the glibc       wrapper function falls back to the use ofrename().  Whenoldpath       andnewpath are relative pathnames, glibc constructs pathnames       based on the symbolic links in/proc/self/fd that correspond to       theolddirfd andnewdirfd arguments.

BUGS top

       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.  Seelink(2) for a       similar problem.

COLOPHON top

       This page is part of theman-pages (Linux kernel and C library       user-space interface documentation) project.  Information about       the project can be found at        ⟨https://www.kernel.org/doc/man-pages/⟩.  If you have a bug report       for this manual page, see       ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.       This page was obtained from the tarball man-pages-6.15.tar.gz       fetched from       ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on       2025-08-11.  If you discover any rendering problems in this HTML       version of the page, or you believe there is a better or more up-       to-date source for the page, or you have corrections or       improvements to the information in this COLOPHON (which isnot       part of the original manual page), send a mail to       man-pages@man7.orgLinux man-pages 6.15            2025-05-17rename(2)

Pages that refer to this page:exch(1), mv(1), F_NOTIFY(2const), io_uring_enter2(2), io_uring_enter(2), link(2), open(2), rmdir(2), symlink(2), syscalls(2), unlink(2), io_uring_prep_rename(3), io_uring_prep_renameat(3), remove(3), cpuset(7), inotify(7), signal-safety(7), symlink(7), lsof(8), mount(8)