rename

RENAME(3POSIX)              POSIX Programmer's Manual             RENAME(3POSIX)



PROLOG
       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.


NAME
       rename, renameat — rename file relative to directory file descriptor

SYNOPSIS
       #include <stdio.h>

       int rename(const char *old, const char *new);
       int renameat(int oldfd, const char *old, int newfd,
           const char *new);

DESCRIPTION
       For rename(): 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‐2008 defers to the ISO C standard.

       The rename() function shall change the name of a file. The old argument
       points to the pathname of the file to be renamed. The new argument points
       to the new pathname of the file.  If the new argument does not resolve to
       an existing directory entry for a file of type directory and the new
       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 the old or new argument names a symbolic link, rename() shall
       operate on the symbolic link itself, and shall not resolve the last
       component of the argument. If the old argument and the new 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 the old argument points to the pathname of a file that is not a
       directory, the new argument shall not point to the pathname of a
       directory. If the link named by the new argument exists, it shall be
       removed and old renamed to new.  In this case, a link named new shall
       remain visible to other processes throughout the renaming operation and
       refer either to the file referred to by new or old before the operation
       began. Write access permission is required for both the directory
       containing old and the directory containing new.

       If the old argument points to the pathname of a directory, the new
       argument shall not point to the pathname of a file that is not a
       directory. If the directory named by the new argument exists, it shall be
       removed and old renamed to new.  In this case, a link named new shall
       exist throughout the renaming operation and shall refer either to the
       directory referred to by new or old before the operation began. If new
       names an existing directory, it shall be required to be an empty
       directory.

       If either pathname argument refers to a path whose final component is
       either dot or dot-dot, rename() shall fail.

       If the old argument points to a pathname of a symbolic link, the symbolic
       link shall be renamed. If the new argument points to a pathname of a
       symbolic link, the symbolic link shall be removed.

       The old pathname shall not name an ancestor directory of the new
       pathname. Write access permission is required for the directory
       containing old and the directory containing new.  If the old argument
       points to the pathname of a directory, write access permission may be
       required for the directory named by old, and, if it exists, the directory
       named by new.

       If the link named by the new 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 before rename() 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 the rename() function fails for any reason other than [EIO], any file
       named by new shall be unaffected.

       The renameat() function shall be equivalent to the rename() function
       except in the case where either old or new specifies a relative path. If
       old is a relative path, the file to be renamed is located relative to the
       directory associated with the file descriptor oldfd instead of the
       current working directory. If new is a relative path, the same happens
       only relative to the directory associated with newfd.  If the file
       descriptor was opened without O_SEARCH, the function shall check whether
       directory searches are permitted using the current permissions of the
       directory underlying the file descriptor. If the file descriptor was
       opened with O_SEARCH, the function shall not perform the check.

       If renameat() is passed the special value AT_FDCWD in the oldfd or newfd
       parameter, the current working directory shall be used in the
       determination of the file for the respective path parameter.

RETURN VALUE
       Upon successful completion, the rename() function shall return 0.
       Otherwise, it shall return −1, errno shall be set to indicate the error,
       and neither the file named by old nor the file named by new shall be
       changed or created.

       Upon successful completion, the renameat() function shall return 0.
       Otherwise, it shall return −1 and set errno to indicate the error.

ERRORS
       The rename() and renameat() functions shall fail if:

       EACCES A component of either path prefix denies search permission; or one
              of the directories containing old or new denies write permissions;
              or, write permission is required and is denied for a directory
              pointed to by the old or new arguments.

       EBUSY  The directory named by old or new is currently in use by the
              system or another process, and the implementation considers this
              an error.

       [EEXIST] or [ENOTEMPTY]
                   The link named by new is a directory that is not an empty
                   directory.

       EINVAL      The old pathname names an ancestor directory of the new
                   pathname, or either pathname argument contains a final
                   component that is dot or dot-dot.

       EIO         A physical I/O error has occurred.

       EISDIR      The new argument points to a directory and the old argument
                   points to a file that is not a directory.

       ELOOP       A loop exists in symbolic links encountered during resolution
                   of the path argument.

       EMLINK      The file named by old is a directory, and the link count of
                   the parent directory of new would exceed {LINK_MAX}.

       ENAMETOOLONG
                   The length of a component of a pathname is longer than
                   {NAME_MAX}.

       ENOENT      The link named by old does not name an existing file, a
                   component of the path prefix of new does not exist, or either
                   old or new points to an empty string.

       ENOSPC      The directory that would contain new cannot be extended.

       ENOTDIR     A component of either path prefix names an existing file that
                   is neither a directory nor a symbolic link to a directory; or
                   the old argument names a directory and the new argument names
                   a non-directory file; or the old 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 the old argument names an existing non-
                   directory file and the new argument names a nonexistent file,
                   contains at least one non-<slash> character, and ends with
                   one or more trailing <slash> characters; or the new argument
                   names an existing non-directory file, contains at least one
                   non-<slash> character, and ends with one or more trailing
                   <slash> characters.

       EPERM or EACCES
                   The S_ISVTX flag is set on the directory containing the file
                   referred to by old and the process does not satisfy the
                   criteria specified in the Base Definitions volume of
                   POSIX.1‐2008, Section 4.2, Directory Protection with respect
                   to old; or new 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‐2008, Section 4.2, Directory
                   Protection with respect to this file.

       EROFS       The requested operation requires writing in a directory on a
                   read-only file system.

       EXDEV       The links named by new and old are on different file systems
                   and the implementation does not support links between file
                   systems.

       In addition, the renameat() function shall fail if:

       EACCES oldfd or newfd was not opened with O_SEARCH and the permissions of
              the directory underlying oldfd or newfd respectively do not permit
              directory searches.

       EBADF  The old argument does not specify an absolute path and the oldfd
              argument is neither AT_FDCWD nor a valid file descriptor open for
              reading or searching, or the new argument does not specify an
              absolute path and the newfd argument is neither AT_FDCWD nor a
              valid file descriptor open for reading or searching.

       ENOTDIR
              The old or new argument is not an absolute path and oldfd or
              newfd, respectively, is a file descriptor associated with a non-
              directory file.

       The rename() and renameat() functions may fail if:

       EBUSY  The file named by the old or new arguments is a named STREAM.

       ELOOP  More than {SYMLOOP_MAX} symbolic links were encountered during
              resolution of the path 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 by new exists and is the last directory entry to a
              pure procedure (shared text) file that is being executed.

       The following sections are informative.

EXAMPLES
   Renaming a File
       The following example shows how to rename a file named /home/cnd/mod1 to
       /home/cnd/mod2.

           #include <stdio.h>

           int status;
           ...
           status = rename("/home/cnd/mod1", "/home/cnd/mod2");

APPLICATION USAGE
       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.

RATIONALE
       This rename() 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 the new
       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
       of link() and unlink() with directories, thus constraining links to
       directories to those made by mkdir().

       The specification that if old and new 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] in rmdir()
       and [EBUSY] in unlink().  For a discussion of [EXDEV], see link().

       The purpose of the renameat() 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 to rename(), resulting in unspecified behavior. By opening file
       descriptors for the source and target directories and using the
       renameat() function it can be guaranteed that that renamed file is
       located correctly and the resulting file is in the desired directory.

FUTURE DIRECTIONS
       None.

SEE ALSO
       link(), rmdir(), symlink(), unlink()

       The Base Definitions volume of POSIX.1‐2008, Section 4.2, Directory
       Protection, <stdio.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electrical
       and Electronics Engineers, Inc and The Open Group.  (This is POSIX.1-2008
       with the 2013 Technical Corrigendum 1 applied.) 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 at
       http://www.unix.org/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, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                   2013                        RENAME(3POSIX)