rename(S)                      6 January 1993                      rename(S)


 Name

    rename - changes filename

 Syntax


    cc  . . .  -lc


    #include <stdio.h>

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


 Description

    The rename function causes the file or directory whose pathname is the
    string pointed to by old to be henceforth known by the pathname given by
    the string pointed to by new.  The file or directory named old is effec-
    tively removed.  If a file or directory named by the string pointed to by
    new exists prior to the call to the rename function, new is removed.

    If the old argument and the new argument both refer to links to the same
    existing file, the rename function returns successfully and performs no
    other action.

    The old and the new arguments must both point to the pathname of a file
    or they must both point to the pathname of a directory.  If the link
    named by the new argument exists, it is removed and old renamed to new.
    In this case, a link named new exists throughout the the renaming opera-
    tion and refers either to the file referred to by new or old before the
    operation began.  Write access permission is required for both the direc-
    tory containing old and the directory containing new.

    If the old argument points to the pathname of a directory, the new argu-
    ment cannot point to the pathname of a file.  If the directory named by
    the new argument exists, it is removed and old renamed to new.  In this
    case, a link named new exists throughout the renaming operation and
    refers either to the file referred to by new or old before the operation
    began.  Thus, if new names an existing directory, it is required to be an
    empty directory.

    The new pathname cannot 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 zero when it is removed and no process has the file open, the
    space occupied by the file is freed and the file is no longer accessible.
    If one of more processes have the file open when the last link is
    removed, the link is removed before rename returns, but the removal of
    the file contents is postponed until all references to the file have been
    closed.

    Upon successful completion, the rename function marks for update the
    stctime and stmtime fields of the parent directory of each file.

 Return value

    The rename function returns zero if the operation succeeds. A return
    value of -1 indicates that an error has occurred and an error code has
    been stored in errno.

 Diagnostics

    If any of the following conditions occur, the rename function returns -1
    and sets errno to the corresponding value:

    [EACCES]       A component of either path prefix denies search permis-
                   sion; 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 the the old or
                   new arguments.

    [EBUSY]        The directory named by old or new cannot be renamed
                   because it is being used by the system or another process
                   and the implementation considers this to be an error.

    [EEXIST]       The link named by new is a directory containing entries
                   other than dot and dot-dot.

    [ENOTEMPTY]    Same as [EEXIST].

    [EINVAL]       The new directory pathname contains a path prefix that
                   names the old directory.

    [EISDIR]       The new argument points to a directory and the old argu-
                   ment points to a file that is not a directory.

    [ENAMETOOLONG]
                   The length of the old or new argument exceeds {PATHMAX}
                   or a pathname component is longer than {NAMEMAX} while
                   {POSIXNOTRUNC} is in effect.

    [ENOENT]       The link named by the old argument does not exist 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 the new argument
                   names a nondirectory file.

    [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 sys-
                   tems and the implementation does not support links between
                   file systems.


 See also

    link(S), rmdir(S), unlink(S)

 Standards conformance

    rename is conformant with:
    IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C
    Language] (ISO/IEC 9945-1);
    and NIST FIPS 151-1.