huschi.net

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 (consult 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 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.
       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  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-
              tory 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 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(3P)