rename

###

###

###

###

###

###

###

###

###

###

###

###

    RENAME(2)           Linux Programmer's Manual           RENAME(2)

    NAME
           rename - change the name or location of a file

    SYNOPSIS
           #include <unistd.h>

           int rename(const char *oldpath, const char *newpath);

    DESCRIPTION
           rename  renames  a  file, moving it between directories if
           required.

           Any other hard links to the file (as created  using  link)
           are unaffected.

           If  newpath already exists it will be atomically overwrit-
           ten (subject to a few conditions - see ERRORS  below),  so
           that there is no point at which another process attempting
           to access newpath will find it missing.

           If newpath exists but the operation fails for some  reason
           or  the  system  crashes  rename  guarantees  to  leave an
           instance of newpath in place.

           However, when overwriting there will probably be a  window
           in  which both oldpath and newpath refer to the file being
           renamed.

           If oldpath refers to a symbolic link the link is  renamed;
           if  newpath  refers  to  a  symbolic link the link will be
           overwritten.

    RETURN VALUE
           On success, zero is returned.  On error, -1  is  returned,
           and errno is set appropriately.

    ERRORS
           EISDIR  newpath  is  an existing directory, but oldpath is
                   not a directory.

           EXDEV   oldpath and newpath are not on the  same  filesys-
                   tem.

           ENOTEMPTY
                   newpath is a non-empty directory.

           EBUSY   newpath  exists  and is the current working direc-
                   tory or root directory of some process.

           EINVAL  An attempt was made to make a directory  a  subdi-
                   rectory of itself.

           EMLINK  oldpath already has the maximum number of links to
                   it, or  it  was  a  directory  and  the  directory

    Linux 0.99.7               24 July 1993                         1

    RENAME(2)           Linux Programmer's Manual           RENAME(2)

                   containing  newpath  has  the  maximum  number  of
                   links.

           ENOTDIR A component used as a directory in oldpath or new-
                   path is not, in fact, a directory.

           EFAULT  oldpath  or newpath points outside your accessible
                   address space.

           EACCES  Write access to the directory  containing  oldpath
                   or newpath is not allowed for the process's effec-
                   tive uid, or one of the directories in oldpath  or
                   newpath did not allow search (execute) permission,
                   or oldpath was a directory and did not allow write
                   permission (needed to update the ..  entry).

           EPERM   The  directory  containing  oldpath has the sticky
                   bit set and the process's effective uid is neither
                   the  uid of the file to be deleted nor that of the
                   directory containing it, or  the  filesystem  con-
                   taining  pathname does not support renaming of the
                   type requested.

           ENAMETOOLONG
                   oldpath or newpath was too long.

           ENOENT  A directory component in oldpath  or  newpath does
                   not exist or is a dangling symbolic link.

           ENOMEM  Insufficient kernel memory was available.

           EROFS   The file is on a read-only filesystem.

           ELOOP   oldpath  or newpath contains a reference to a cir-
                   cular symbolic link,  ie  a  symbolic  link  whose
                   expansion contains a reference to itself.

           ENOSPC  The device containing the file has no room for the
                   new directory entry.

    CONFORMING TO
           POSIX, BSD 4.3, ANSI C

    BUGS
           Currently (Linux 0.99pl7) most of the  filesystems  except
           Minix  will  not  allow  any overwriting renames involving
           directories. You get EEXIST if you try.

           On NFS filesystems, you can not assume that  only  because
           the  operation  failed,  the file was not renamed.  If the
           server does the rename operation  and  then  crashes,  the
           retransmitted  RPC which will be processed when the server
           is up again causes a failure.  The application is expected
           to deal with this.  See link(2) for a similar problem.

    Linux 0.99.7               24 July 1993                         2

    RENAME(2)           Linux Programmer's Manual           RENAME(2)

### SEE ALSO

link, unlink, symlink,

###

    Linux 0.99.7               24 July 1993                         3

Top | Master Index | Keywords | Functions

This manual page was brought to you by mjl_man V-2.0