HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
PROLOG |NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |EXAMPLES |APPLICATION USAGE |RATIONALE |FUTURE DIRECTIONS |SEE ALSO |COPYRIGHT | |
RENAME(3P) POSIX Programmer's ManualRENAME(3P)This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.
rename, renameat — rename file
#include <stdio.h> int rename(const char *old, const char *new); #include <fcntl.h> int renameat(intoldfd, const char *old, intnewfd, const char *new);
Forrename(): The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of POSIX.1‐2017 defers to the ISO C standard. Therename() function shall change the name of a file. Theold argument points to the pathname of the file to be renamed. Thenew argument points to the new pathname of the file. If thenew argument does not resolve to an existing directory entry for a file of type directory and thenew argument contains at least one non-<slash> character and ends with one or more trailing <slash> characters after all symbolic links have been processed,rename() shall fail. If either theold ornew argument names a symbolic link,rename() shall operate on the symbolic link itself, and shall not resolve the last component of the argument. If theold argument and thenew argument resolve to either the same existing directory entry or different directory entries for the same existing file,rename() shall return successfully and perform no other action. If theold argument points to the pathname of a file that is not a directory, thenew argument shall not point to the pathname of a directory. If the link named by thenew argument exists, it shall be removed andold renamed tonew. In this case, a link namednew shall remain visible to other threads throughout the renaming operation and refer either to the file referred to bynew orold before the operation began. Write access permission is required for both the directory containingold and the directory containingnew. If theold argument points to the pathname of a directory, thenew argument shall not point to the pathname of a file that is not a directory. If the directory named by thenew argument exists, it shall be removed andold renamed tonew. In this case, a link namednew shall exist throughout the renaming operation and shall refer either to the directory referred to bynew orold before the operation began. Ifnew names an existing directory, it shall be required to be an empty directory. If eitherpathname argument refers to a path whose final component is either dot or dot-dot,rename() shall fail. If theold argument points to a pathname of a symbolic link, the symbolic link shall be renamed. If thenew argument points to a pathname of a symbolic link, the symbolic link shall be removed. Theold pathname shall not name an ancestor directory of thenew pathname. Write access permission is required for the directory containingold and the directory containingnew. If theold argument points to the pathname of a directory, write access permission may be required for the directory named byold, and, if it exists, the directory named bynew. If the link named by thenew argument exists and the file's link count becomes 0 when it is removed and no process has the file open, the space occupied by the file shall be freed and the file shall no longer be accessible. If one or more processes have the file open when the last link is removed, the link shall be removed beforerename() returns, but the removal of the file contents shall be postponed until all references to the file are closed. Upon successful completion,rename() shall mark for update the last data modification and last file status change timestamps of the parent directory of each file. If therename() function fails for any reason other than[EIO], any file named bynew shall be unaffected. Therenameat() function shall be equivalent to therename() function except in the case where eitherold ornew specifies a relative path. Ifold is a relative path, the file to be renamed is located relative to the directory associated with the file descriptoroldfd instead of the current working directory. Ifnew is a relative path, the same happens only relative to the directory associated withnewfd. If the access mode of the open file description associated with the file descriptor is not O_SEARCH, the function shall check whether directory searches are permitted using the current permissions of the directory underlying the file descriptor. If the access mode is O_SEARCH, the function shall not perform the check. Ifrenameat() is passed the special value AT_FDCWD in theoldfd ornewfd parameter, the current working directory shall be used in the determination of the file for the respectivepath parameter.
Upon successful completion, therename() function shall return 0. Otherwise, it shall return -1,errno shall be set to indicate the error, and neither the file named byold nor the file named bynew shall be changed or created. Upon successful completion, therenameat() function shall return 0. Otherwise, it shall return -1 and seterrno to indicate the error.
Therename() andrenameat() functions shall fail if:EACCESA component of either path prefix denies search permission; or one of the directories containingold ornew denies write permissions; or, write permission is required and is denied for a directory pointed to by theold ornew arguments.EBUSYThe directory named byold ornew is currently in use by the system or another process, and the implementation considers this an error. [EEXIST] or [ENOTEMPTY] The link named bynew is a directory that is not an empty directory.EINVALTheold pathname names an ancestor directory of thenew pathname, or either pathname argument contains a final component that is dot or dot-dot.EIOA physical I/O error has occurred.EISDIRThenew argument points to a directory and theold argument points to a file that is not a directory.ELOOPA loop exists in symbolic links encountered during resolution of thepath argument.EMLINKThe file named byold is a directory, and the link count of the parent directory ofnew would exceed {LINK_MAX}.ENAMETOOLONG The length of a component of a pathname is longer than {NAME_MAX}.ENOENTThe link named byold does not name an existing file, a component of the path prefix ofnew does not exist, or eitherold ornew points to an empty string.ENOSPCThe directory that would containnew cannot be extended.ENOTDIRA component of either path prefix names an existing file that is neither a directory nor a symbolic link to a directory; or theold argument names a directory and thenew argument names a non-directory file; or theold argument contains at least one non-<slash> character and ends with one or more trailing <slash> characters and the last pathname component names an existing file that is neither a directory nor a symbolic link to a directory; or theold argument names an existing non-directory file and thenew argument names a nonexistent file, contains at least one non-<slash> character, and ends with one or more trailing <slash> characters; or thenew argument names an existing non-directory file, contains at least one non-<slash> character, and ends with one or more trailing <slash> characters.EPERMorEACCES The S_ISVTX flag is set on the directory containing the file referred to byold and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1‐2017,Section 4.3,DirectoryProtection with respect toold; ornew refers to an existing file, the S_ISVTX flag is set on the directory containing this file, and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1‐2017,Section 4.3,Directory Protection with respect to this file.EROFSThe requested operation requires writing in a directory on a read-only file system.EXDEVThe links named bynew andold are on different file systems and the implementation does not support links between file systems. In addition, therenameat() function shall fail if:EACCESThe access mode of the open file description associated witholdfd ornewfd is not O_SEARCH and the permissions of the directory underlyingoldfd ornewfd, respectively, do not permit directory searches.EBADFTheold argument does not specify an absolute path and theoldfd argument is neither AT_FDCWD nor a valid file descriptor open for reading or searching, or thenew argument does not specify an absolute path and thenewfd argument is neither AT_FDCWD nor a valid file descriptor open for reading or searching.ENOTDIR Theold ornew argument is not an absolute path andoldfd ornewfd, respectively, is a file descriptor associated with a non-directory file. Therename() andrenameat() functions may fail if:EBUSYThe file named by theold ornew arguments is a named STREAM.ELOOPMore than {SYMLOOP_MAX} symbolic links were encountered during resolution of thepath argument.ENAMETOOLONG The length of a pathname exceeds {PATH_MAX}, or pathname resolution of a symbolic link produced an intermediate result with a length that exceeds {PATH_MAX}.ETXTBSY The file named bynew exists and is the last directory entry to a pure procedure (shared text) file that is being executed.The following sections are informative.Renaming a File The following example shows how to rename a file named/home/cnd/mod1to/home/cnd/mod2. #include <stdio.h> int status; ... status = rename("/home/cnd/mod1", "/home/cnd/mod2");Some implementations mark for update the last file status change timestamp of renamed files and some do not. Applications which make use of the last file status change timestamp may behave differently with respect to renamed files unless they are designed to allow for either behavior.
Thisrename() function is equivalent for regular files to that defined by the ISO C standard. Its inclusion here expands that definition to include actions on directories and specifies behavior when thenew parameter names a file that already exists. That specification requires that the action of the function be atomic. One of the reasons for introducing this function was to have a means of renaming directories while permitting implementations to prohibit the use oflink() andunlink() with directories, thus constraining links to directories to those made bymkdir(). The specification that ifold andnew refer to the same file is intended to guarantee that: rename("x", "x"); does not remove the file. Renaming dot or dot-dot is prohibited in order to prevent cyclical file system paths. See also the descriptions of[ENOTEMPTY]and[ENAMETOOLONG]inrmdir() and[EBUSY]inunlink(). For a discussion of[EXDEV], seelink(). The purpose of therenameat() function is to rename files in directories other than the current working directory without exposure to race conditions. Any part of the path of a file could be changed in parallel to a call torename(), resulting in unspecified behavior. By opening file descriptors for the source and target directories and using therenameat() function it can be guaranteed that that renamed file is located correctly and the resulting file is in the desired directory.None.
link(3p),rmdir(3p),symlink(3p),unlink(3p) The Base Definitions volume of POSIX.1‐2017,Section 4.3,Directory Protection,fcntl.h(0p),stdio.h(0p)
Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online athttp://www.opengroup.org/unix/online.html . Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, seehttps://www.kernel.org/doc/man-pages/reporting_bugs.html .IEEE/The Open Group 2017RENAME(3P)Pages that refer to this page:stdio.h(0p), mv(1p), link(3p), rmdir(3p), symlink(3p), unlink(3p)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |