renameat(2)




NAME

     rename, renameat - change the name of a file


SYNOPSIS

     #include <stdio.h>

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

     int renameat(int fromfd, const char *old,  int  tofd,  const
     char *new);


DESCRIPTION

     The  rename() function changes 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 path name of the file.

     The renameat() function renames an  entry  in  a  directory,
     possibly  moving  the entry into a different directory.  See
     fsattr(5). If the old argument  is  an  absolute  path,  the
     fromfd is ignored.  Otherwise it is resolved relative to the
     fromfd argument rather than the current  working  directory.
     Similarly,  if  the  new  argument  is  not  absolute, it is
     resolved relative to the tofd argument.  If either fromfd or
     tofd  have  the  value  AT_FDCWD,  defined in <fcntl.h>, and
     their respective paths are relative, the  path  is  resolved
     relative to the current working directory.

     Current   implementation   restrictions   will   cause   the
     renameat() function to return an error if an attempt is made
     to rename an extended attribute  file  to  a  regular  (non-
     attribute)  file, or to rename a regular file to an extended
     attribute file.

     If old and new both refer to the  same  existing  file,  the
     rename()  and  renameat()  functions return successfully and
     performs no other action.

     If old points to the pathname of a file that is not a direc-
     tory,  new must not point to the pathname of a directory. If
     the link named by new exists, it will  be  removed  and  old
     will  be renamed to new. In this case, a link named new must
     remain visible to other processes  throughout  the  renaming
     operation  and  will refer to either the file referred to by
     new or the file referred to  as  old  before  the  operation
     began.

     If old points to the pathname of a directory, new  must  not
     point  to the pathname of a file that is not a directory. If
     the directory named by new exists, it will  be  removed  and
     old  will  be renamed to new. In this case, a link named new
     will exist throughout the renaming operation and will  refer
     to  either the file referred to by new  or the file referred
     to as old before the operation began. Thus, if new names  an
     existing directory, it must be an empty directory.

     The new pathname must not contain a path prefix  that  names
     old. Write access permission is required for both the direc-
     tory containing old and the directory containing new. If old
     points to the  pathname of a directory, write access permis-
     sion is required for the  directory named by old, and, if it
     exists, the directory  named by new.

     If the directory containing old has the sticky bit set,   at
     least  one  of the following conditions listed below must be
     true:

        o  the user must own old

        o  the user must own the directory containing old

        o  old must be writable by the user

        o  the user must be a privileged user

     If new exists, and the directory containing new is  writable
     and  has  the sticky bit set, at least  one of the following
     conditions must be true:

        o  the user must own new

        o  the user must own the directory containing new

        o  new must be writable by the user

        o  the user must be a privileged user

     If the link named by  new  exists,  the  file's  link  count
     becomes zero when it is removed, and no process has the file
     open, then  the space occupied by the file will be freed and
     the  file  will  no  longer  be  accessible.  If one or more
     processes have the file open when the last link is  removed,
     the  link  will  be  removed  before  rename() or renameat()
     returns, but the removal of the file contents will be  post-
     poned until all references to the file have been closed.

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


RETURN VALUES

     Upon successful completion, 0 is returned. Otherwise, -1  is
     returned and errno is set to indicate an error.


ERRORS

     The rename() function will fail if:

     EACCES
           A component of either path prefix denies  search  per-
           mission; one of the directories containing old and new
           denies  write  permissions;  or  write  permission  is
           denied by a directory pointed to by old or new.

     EBUSY The new argument is a directory and  the  mount  point
           for a mounted file system.

     EDQUOT
           The directory where the new name entry is being placed
           cannot  be  extended  because the user's quota of disk
           blocks on that file system has been exhausted.

     EEXIST
           The link  named  by  new  is  a  directory  containing
           entries other than `.' (the directory itself) and `..'
           (the parent directory).

     EFAULT
           Either old or new references an invalid address.

     EINVAL
           The new argument directory pathname  contains  a  path
           prefix that names the old directory, or an attempt was
           made to rename a regular file to an extended attribute
           or from an extended attribute to a regular file.

     EISDIR
           The new argument points to a directory but old  points
           to a file that is not a directory.

     ELOOP Too many symbolic links were encountered in  translat-
           ing the pathname.

     ENAMETOOLONG
           The length of old or new exceeds  PATH_MAX, or a path-
           name   component   is   longer  than   NAME_MAX  while
           _POSIX_NO_TRUNC is in effect.

     EMLINK
           The file named by old is a  directory,  and  the  link
           count  of   the  parent  directory of new would exceed
           LINK_MAX.

     ENOENT
           The link named by old 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  old names a directory and new names a nondirectory
           file, or tofd and dirfd in renameat() do not reference
           a directory.

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

     EXDEV The links named by old and new are on  different  file
           systems.

     EIO   An I/O error  occurred  while  making  or  updating  a
           directory entry.

     The renameat() functions will fail if:

     ENOTSUP
           An attempt was made to rename a  regular  file  as  an
           attribute  file  or  to  rename an attribute file as a
           regular file.


USAGE

     When a UFS file system is mounted with logging enabled, file
     system  transactions  that  free blocks from files might not
     actually add those freed blocks to the  file  system's  free
     list  until  some  unspecified  time  in  the  future.  This
     behavior improves file system performance but does not  con-
     form  to the POSIX, Single UNIX Specification, SPARC Confor-
     mance Definition, System  V  Application  Binary  Interface,
     System  V Interface Definition, and X/Open Portability Guide
     Standards, which  require  that  freed  space  be  available
     immediately.  To enable standards conformance regarding file
     deletions or to address the problem of  not  being  able  to
     grow  files  on a relatively full UFS file system even after
     files  have  been  deleted,   disable   UFS   logging   (see
     mount_ufs(1M).


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | See below.                  |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|

     The rename() function is Standard. The  renameat()  function
     is Evolving.


SEE ALSO

     mount_ufs(1M), chmod(2), link(2), unlink(2),  attributes(5),
     fsattr(5)


NOTES

     The system can deadlock if there is a loop in the file  sys-
     tem  graph.  Such  a  loop can occur if there is an entry in
     directory a, a/name1, that is a hard link  to  directory  b,
     and an entry in directory b, b/name2, that is a hard link to
     directory a. When  such  a  loop  exists  and  two  separate
     processes  attempt  to rename a/name1 to b/name2 and b/name2
     to a/name1, the system may deadlock attempting to lock  both
     directories for modification.  Use symbolic links instead of
     hard links  for directories.


Man(1) output converted with man2html