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



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult the corresponding Linux manual page for details of Linux behavior), or the  interface  may  not  be  implemented  on
       Linux.

NAME
       rename - rename a file

SYNOPSIS
       #include <stdio.h>

       int rename(const char *old, const char *new);


DESCRIPTION
       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 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 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 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  new  pathname  shall not contain a path prefix that names old. 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 st_ctime and st_mtime fields 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.

RETURN VALUE
       Upon  successful  completion,  rename() shall return 0; otherwise, -1 shall be returned,   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.

ERRORS
       The rename() function 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 new directory pathname contains a path prefix that names the old directory.

       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 the old or new argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

       ENOENT The link named by old does not name an existing file, 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 is not a directory; or the old argument names a directory and new argument names
              a non-directory file.

       EPERM or EACCES

              The S_ISVTX flag is set on the directory containing the file referred to by old and the caller  is  not  the  file
              owner, nor is the caller the directory owner, nor does the caller have appropriate privileges; or new refers to an
              existing file, the S_ISVTX flag is set on the directory containing this file, and  the  caller  is  not  the  file
              owner, nor is the caller the directory owner, nor does the caller have appropriate privileges.

       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.


       The rename() function 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

              As a result of encountering a symbolic link in resolution of the path argument,  the  length  of  the  substituted
              pathname string exceeded {PATH_MAX}.

       ETXTBSY
              The file to be renamed is 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 st_ctime field of renamed files and some do not. Applications which make use of
       the st_ctime field 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 implementa-
       tions 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() .

FUTURE DIRECTIONS
       None.

SEE ALSO
       link(), rmdir(), symlink(), unlink(), the Base Definitions volume of IEEE Std 1003.1-2001, <stdio.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003  Edition,  Standard  for
       Information  Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copy-
       right (C) 2001-2003 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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                    RENAME(3P)