rename(2)							   System Calls 							 rename(2)

NAME

       rename, renameat - change the name of a file

SYNOPSIS

       #include <stdio.h>

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

       #include <unistd.h>

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

   XPG3
       #include <unistd.h>

       int rename(const char *old, 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 work-
       ing 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 directory, 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 opera-
       tion  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 directory  containing  old
       and  the  directory  containing	new. If old points to the  pathname of a directory, write access permission 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 postponed
       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 permission; one of the directories containing old and new denies write per-
		       missions; 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 direc-
		       tory).

       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 translating the pathname.

       ENAMETOOLONG    The  length  of	old or new exceeds  PATH_MAX, or a pathname 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 directory 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.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |rename()	  is	Standard;  |
       |			     |renameat() is Evolving	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Async-Signal-Safe 	   |
       +-----------------------------+-----------------------------+

SEE ALSO

       chmod(2), link(2), unlink(2), attributes(5), fsattr(5)

NOTES

       The system can deadlock if there is a loop in the file system 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 direc-
       tories for modification.  Use symbolic links instead of hard links  for directories.

SunOS 5.10							    4 Nov 2002								 rename(2)