unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

RENAME(2V)                                                          RENAME(2V)



NAME
       rename - change the name of a file

SYNOPSIS
       int rename(path1, path2)
       char *path1, *path2;

DESCRIPTION
       rename()  renames the link named path1 as path2.  If path2 exists, then
       it is first removed.  If path2 refers to a directory,  it  must  be  an
       empty  directory,  and must not include path1 in its path prefix.  Both
       path1 and path2 must be of the same type (that is, both directories  or
       both  non-directories), and must reside on the same file system.  Write
       access permission is required for both the directory  containing  path1
       and  the  directory  containing path2.  If a rename request relocates a
       directory in the hierarchy, write permission in  the  directory  to  be
       moved is needed, since its entry for the parent directory (..)  must be
       updated.

       rename() guarantees that an instance of path2 will always  exist,  even
       if the system should crash in the middle of the operation.

       If  the  final component of path1 is a symbolic link, the symbolic link
       is renamed, not the file or directory to which it points.

       If the file referred to by path2  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 accessi-
       ble.  If one or more processes have the file open when the last link is
       removed, the link is removed before rename() returns,  but  the  file's
       contents  are  not  removed  until all references to the file have been
       closed.

       Upon successful completion, rename() marks for update the st_ctime  and
       st_mtime fields of the parent directory of each file.

RETURN VALUES
       rename() returns:

       0      on success.

       -1     on failure and sets errno to indicate the error.

ERRORS
       rename() will fail and neither path1 nor path2 will be affected if:

       EACCES              Write access is denied for either path1 or path2.

                           A  component  of the path prefix of either path1 or
                           path2 denies search permission.

                           The requested rename requires writing in  a  direc-
                           tory  with  access permissions that deny write per-
                           mission.

       EBUSY               path2 is a directory and is the mount point  for  a
                           mounted file system.

       EDQUOT              The  directory  in which the entry for the new name
                           is being placed  cannot  be  extended  because  the
                           user's quota of disk blocks on the file system con-
                           taining the directory has been exhausted.

       EFAULT              Either or both of path1 or path2 point outside  the
                           process's allocated address space.

       EINVAL              path1 is a parent directory of path2.

                           An attempt was made to rename `.'  or `..'.

       EIO                 An I/O error occurred while reading from or writing
                           to the file system.

       EISDIR              path2 points to a directory and path1 points  to  a
                           file that is not a directory.

       ELOOP               Too  many  symbolic  links  were  encountered while
                           translating either path1 or path2.

       ENAMETOOLONG        The  length  of  either   path   argument   exceeds
                           {PATH_MAX}.

                           A  pathname  component  is  longer  than {NAME_MAX}
                           while {_POSIX_NO_TRUNC} is  in  effect  (see  path-
                           conf(2V)).

       ENOENT              A  component  of the path prefix of either path1 or
                           path2 does not exist.

                           The file named by path1 does not exist.

       ENOSPC              The directory in which the entry for the  new  name
                           is being placed cannot be extended because there is
                           no space left on the  file  system  containing  the
                           directory.

       ENOTDIR             A  component  of the path prefix of either path1 or
                           path2 is not a directory.

                           path1 names a directory and path2 names a nondirec-
                           tory file.

       ENOTEMPTY           path2 is a directory and is not empty.

       EROFS               The  requested  rename requires writing in a direc-
                           tory on a read-only file system.

       EXDEV               The link named by path2 and the file named by path1
                           are on different logical devices (file systems).

SYSTEM V ERRORS
       In addition to the above, the following may also occur:

       ENOENT              path1 or path2 points to an empty string.

SEE ALSO
       open(2V)

WARNINGS
       The  system can deadlock if a loop in the file system graph is present.
       This loop takes the form of an entry in directory a, say a/file1, being
       a  hard  link to directory b, and an entry in directory b, say b/file2,
       being a hard link to directory a.  When such a loop exists and two sep-
       arate processes attempt to perform `rename a/file1 b/file2' and `rename
       b/file2 a/file1', respectively, the system may deadlock  attempting  to
       lock  both  directories  for  modification.   Hard links to directories
       should not be used.  System administrators should  use  symbolic  links
       instead.



                                21 January 1990                     RENAME(2V)