rename

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 direc-
       tory. 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 con-
       taining 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 direc-
       tory. 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 direc-
       tory.

       If  the  old argument points to a pathname of a symbolic link, the sym-
       bolic 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  direc-
       tory 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.

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 per-
              missions; 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 direc-
              tory.

       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-direc-
              tory 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  appro-
              priate  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 direc-

       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 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");

       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, Copyright (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.opengroup.org/unix/online.html .



IEEE/The Open Group                  2003                            RENAME(P)