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

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  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 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 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 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 nei-
       ther 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 permis-
	      sions; 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 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() .

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 Technol-
       ogy -- 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)