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



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       rename, renameat -- rename file

SSYYNNOOPPSSIISS
       #include <stdio.h>

       int rename(const char *_o_l_d, const char *_n_e_w);

       #include <fcntl.h>

       int renameat(int _o_l_d_f_d, const char *_o_l_d, int _n_e_w_f_d,
           const char *_n_e_w);

DDEESSCCRRIIPPTTIIOONN
       For _r_e_n_a_m_e(): 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.

       The _r_e_n_a_m_e() function shall change the name of a file. The _o_l_d argument
       points to the pathname of the file to be renamed. The _n_e_w argument
       points to the new pathname of the file.  If the _n_e_w argument does not
       resolve to an existing directory entry for a file of type directory and
       the _n_e_w argument contains at least one non-<slash> character and ends
       with one or more trailing <slash> characters after all symbolic links
       have been processed, _r_e_n_a_m_e() shall fail.

       If either the _o_l_d or _n_e_w argument names a symbolic link, _r_e_n_a_m_e() shall
       operate on the symbolic link itself, and shall not resolve the last
       component of the argument. If the _o_l_d argument and the _n_e_w argument
       resolve to either the same existing directory entry or different
       directory entries for the same existing file, _r_e_n_a_m_e() shall return
       successfully and perform no other action.

       If the _o_l_d argument points to the pathname of a file that is not a
       directory, the _n_e_w argument shall not point to the pathname of a
       directory. If the link named by the _n_e_w argument exists, it shall be
       removed and _o_l_d renamed to _n_e_w.  In this case, a link named _n_e_w shall
       remain visible to other threads throughout the renaming operation and
       refer either to the file referred to by _n_e_w or _o_l_d before the operation
       began. Write access permission is required for both the directory
       containing _o_l_d and the directory containing _n_e_w.

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

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

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

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

       If the link named by the _n_e_w 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 _r_e_n_a_m_e()
       returns, but the removal of the file contents shall be postponed until
       all references to the file are closed.

       Upon successful completion, _r_e_n_a_m_e() shall mark for update the last
       data modification and last file status change timestamps of the parent
       directory of each file.

       If the _r_e_n_a_m_e() function fails for any reason other than [[EEIIOO]], any
       file named by _n_e_w shall be unaffected.

       The _r_e_n_a_m_e_a_t() function shall be equivalent to the _r_e_n_a_m_e() function
       except in the case where either _o_l_d or _n_e_w specifies a relative path.
       If _o_l_d is a relative path, the file to be renamed is located relative
       to the directory associated with the file descriptor _o_l_d_f_d instead of
       the current working directory. If _n_e_w is a relative path, the same
       happens only relative to the directory associated with _n_e_w_f_d.  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.

       If _r_e_n_a_m_e_a_t() is passed the special value AT_FDCWD in the _o_l_d_f_d or
       _n_e_w_f_d parameter, the current working directory shall be used in the
       determination of the file for the respective _p_a_t_h parameter.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, the _r_e_n_a_m_e() function shall return 0.
       Otherwise, it shall return -1, _e_r_r_n_o shall be set to indicate the
       error, and neither the file named by _o_l_d nor the file named by _n_e_w
       shall be changed or created.

       Upon successful completion, the _r_e_n_a_m_e_a_t() function shall return 0.
       Otherwise, it shall return -1 and set _e_r_r_n_o to indicate the error.

EERRRROORRSS
       The _r_e_n_a_m_e() and _r_e_n_a_m_e_a_t() functions shall fail if:

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

       EEBBUUSSYY  The directory named by _o_l_d or _n_e_w is currently in use by the
              system or another process, and the implementation considers this
              an error.

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

       EEIINNVVAALL      The _o_l_d pathname names an ancestor directory of the _n_e_w
                   pathname, or either pathname argument contains a final
                   component that is dot or dot-dot.

       EEIIOO         A physical I/O error has occurred.

       EEIISSDDIIRR      The _n_e_w argument points to a directory and the _o_l_d argument
                   points to a file that is not a directory.

       EELLOOOOPP       A loop exists in symbolic links encountered during
                   resolution of the _p_a_t_h argument.

       EEMMLLIINNKK      The file named by _o_l_d is a directory, and the link count of
                   the parent directory of _n_e_w would exceed {LINK_MAX}.

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

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

       EENNOOSSPPCC      The directory that would contain _n_e_w cannot be extended.

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

       EEPPEERRMM or EEAACCCCEESS
                   The S_ISVTX flag is set on the directory containing the
                   file referred to by _o_l_d and the process does not satisfy
                   the criteria specified in the Base Definitions volume of
                   POSIX.1-2017, _S_e_c_t_i_o_n _4_._3, _D_i_r_e_c_t_o_r_y _P_r_o_t_e_c_t_i_o_n with
                   respect to _o_l_d; or _n_e_w 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, _S_e_c_t_i_o_n _4_._3,
                   _D_i_r_e_c_t_o_r_y _P_r_o_t_e_c_t_i_o_n with respect to this file.

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

       EEXXDDEEVV       The links named by _n_e_w and _o_l_d are on different file
                   systems and the implementation does not support links
                   between file systems.

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

       EEAACCCCEESS The access mode of the open file description associated with
              _o_l_d_f_d or _n_e_w_f_d is not O_SEARCH and the permissions of the
              directory underlying _o_l_d_f_d or _n_e_w_f_d, respectively, do not permit
              directory searches.

       EEBBAADDFF  The _o_l_d argument does not specify an absolute path and the _o_l_d_f_d
              argument is neither AT_FDCWD nor a valid file descriptor open
              for reading or searching, or the _n_e_w argument does not specify
              an absolute path and the _n_e_w_f_d argument is neither AT_FDCWD nor
              a valid file descriptor open for reading or searching.

       EENNOOTTDDIIRR
              The _o_l_d or _n_e_w argument is not an absolute path and _o_l_d_f_d or
              _n_e_w_f_d, respectively, is a file descriptor associated with a non-
              directory file.

       The _r_e_n_a_m_e() and _r_e_n_a_m_e_a_t() functions may fail if:

       EEBBUUSSYY  The file named by the _o_l_d or _n_e_w arguments is a named STREAM.

       EELLOOOOPP  More than {SYMLOOP_MAX} symbolic links were encountered during
              resolution of the _p_a_t_h argument.

       EENNAAMMEETTOOOOLLOONNGG
              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}.

       EETTXXTTBBSSYY
              The file named by _n_e_w exists and is the last directory entry to
              a pure procedure (shared text) file that is being executed.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   RReennaammiinngg aa FFiillee
       The following example shows how to rename a file named //hhoommee//ccnndd//mmoodd11
       to //hhoommee//ccnndd//mmoodd22.


           #include <stdio.h>

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

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       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.

RRAATTIIOONNAALLEE
       This _r_e_n_a_m_e() 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 _n_e_w
       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 _l_i_n_k() and _u_n_l_i_n_k() with directories, thus constraining links to
       directories to those made by _m_k_d_i_r().

       The specification that if _o_l_d and _n_e_w 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 [[EENNOOTTEEMMPPTTYY]] and [[EENNAAMMEETTOOOOLLOONNGG]] in _r_m_d_i_r()
       and [[EEBBUUSSYY]] in _u_n_l_i_n_k().  For a discussion of [[EEXXDDEEVV]], see _l_i_n_k().

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

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _l_i_n_k(), _r_m_d_i_r(), _s_y_m_l_i_n_k(), _u_n_l_i_n_k()

       The Base Definitions volume of POSIX.1-2017, _S_e_c_t_i_o_n _4_._3, _D_i_r_e_c_t_o_r_y
       _P_r_o_t_e_c_t_i_o_n, <<ffccnnttll..hh>>, <<ssttddiioo..hh>>

CCOOPPYYRRIIGGHHTT
       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 at http://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, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                            RENAME(3)
