home | help
RENAME(2)		       System Calls Manual		       RENAME(2)

NAME
     rename, renameat, renamex_np, renameatx_np -- change the name of a file

SYNOPSIS
     #include <stdio.h>

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

     int
     renameat(int fromfd, const char *from, int tofd, const char *to);

     int
     renamex_np(const char *from, const char *to, unsigned int flags);

     int
     renameatx_np(int fromfd, const char *from, int tofd, const char *to,
	 unsigned int flags);

DESCRIPTION
     The  rename()  system  call causes the link named old to be renamed as new.
     If new exists, it is first removed.  Both old and new must be of  the  same
     type (that is, both must be either directories or non-directories) and must
     reside on the same file system.

     The rename() system call guarantees that an instance of new will always ex-
     ist, even if the system should crash in the middle of the operation.

     If  the final component of old is a symbolic link, the symbolic link is re-
     named, not the file or directory to which it points.

     The renameat() system call is equivalent to rename()  except  in  the  case
     where  either  from or to specifies a relative path.  If from is a relative
     path, the file to be renamed is located relative to the  directory  associ-
     ated  with the file descriptor fromfd instead of the current working direc-
     tory.  If the to is a relative path, the same happens only relative to  the
     directory	associated  with  tofd.  If the renameat() is passed the special
     value AT_FDCWD in the fromfd or tofd parameter, the current working  direc-
     tory is used in the determination of the file for the respective path para-
     meter.

     The renamex_np() and renameatx_np() system calls are similar to their coun-
     terparts except that they take a flags argument.  Values for flags are con-
     structed with below bits set:

	   RENAME_SWAP
		   On	file   systems	 that  support	it  (see  getattrlist(2)
		   VOL_CAP_INT_RENAME_SWAP), it will cause the source and target
		   to be atomically swapped.  Source and target need not  be  of
		   the	same type, i.e. it is possible to swap a file with a di-
		   rectory.  EINVAL is returned in case of bitwise-inclusive  OR
		   with RENAME_EXCL.

	   RENAME_EXCL
		   On	file   systems	 that  support	it  (see  getattrlist(2)
		   VOL_CAP_INT_RENAME_EXCL), it will cause EEXIST to be returned
		   if the destination already exists. EINVAL is returned in case
		   of bitwise-inclusive OR with RENAME_SWAP.

CAVEATS
     The system can deadlock if a loop is present  in  the  file  system  graph.
     This loop takes the form of an entry in directory `a', say `a/foo', being a
     hard link to directory `b', and an entry in directory `b', say `b/bar', be-
     ing a hard link to directory `a'.	When such a loop exists and two separate
     processes attempt to perform `rename a/foo b/bar' and `rename b/bar a/foo',
     respectively,  the  system may deadlock attempting to lock both directories
     for modification.

     Whether or not hard links to directories are supported is specific  to  the
     underlying filesystem implementation.

     It  is  recommended  that	any  hard  links to directories in an underlying
     filesystem should be replaced by symbolic links by the system administrator
     to avoid the possibility of deadlocks.

     Moving or renaming a file or directory into a  directory  with  inheritable
     ACLs does not result in ACLs being set on the file or directory. Use acl(3)
     in conjunction with rename() to set ACLs on the file or directory.

RETURN VALUES
     A 0 value is returned if the operation succeeds, otherwise rename() returns
     -1 and the global variable errno indicates the reason for the failure.

ERRORS
     The  rename()  system call will fail and neither of the argument files will
     be affected if:

     [EACCES]		A component of either path prefix denies search  permis-
			sion.

     [EACCES]		The  requested operation requires writing in a directory
			(e.g., new, new/..,  or  old/..)  whose  modes	disallow
			this.

     [EDQUOT]		The directory in which the entry for the new name is be-
			ing  placed  cannot be extended because the user's quota
			of disk blocks on the file system containing the  direc-
			tory has been exhausted.

     [EEXIST]		flags has RENAME_EXCL set but new already exists.

     [EFAULT]		Path  points  outside  the  process's  allocated address
			space.

     [EINVAL]		Old is a parent directory of new, or an attempt is  made
			to  rename  `.'  or  `..'.  If RENAME_SWAP is used, then
			EINVAL will also be returned if new is a  parent  direc-
			tory  of  old.	If both RENAME_SWAP and RENAME_EXCL bits
			are set in flags, then EINVAL will be returned.

     [EINVAL]		flags has an invalid value.

     [EIO]		An I/O error occurs while making or updating a directory
			entry.

     [EISDIR]		new is a directory, but old is not a directory.

     [ELOOP]		Too many symbolic links are encountered  in  translating
			either	pathname.   This  is taken to be indicative of a
			looping symbolic link.

     [ENAMETOOLONG]	A component of a pathname exceeds {NAME_MAX} characters,
			or an entire path name exceeds {PATH_MAX} characters.

     [ENOENT]		A component of the old path does not exist,  or  a  path
			prefix of new does not exist.

     [ENOENT]		flags has RENAME_SWAP set but new does not exist.

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

     [ENOTDIR]		A component of either path prefix is not a directory.

     [ENOTDIR]		old is a directory, but new is not a directory.

     [ENOTEMPTY]	New is a directory and is not empty.

     [ENOTSUP]		flags has a value that is not supported by the file sys-
			tem.

     [EPERM]		The directory containing old is marked sticky, and  nei-
			ther  the  containing directory nor old are owned by the
			effective user ID.

     [EPERM]		The new file exists, the  directory  containing  new  is
			marked	sticky, and neither the containing directory nor
			new are owned by the effective user ID.

     [EROFS]		The requested link requires writing in a directory on  a
			read-only file system.

     [EXDEV]		The  link  named by new and the file named by old are on
			different logical devices  (file  systems).   Note  that
			this  error code will not be returned if the implementa-
			tion permits cross-device links.

     The renameat() and renameatx_np() calls may also fail with:

     [EBADF]		The from argument does not specify an absolute path  and
			the fromfd argument is neither AT_FDCWD nor a valid file
			descriptor  open  for searching, or the to argument does
			not specify an absolute path and the  tofd  argument  is
			neither  AT_FDCWD  nor	a valid file descriptor open for
			searching.

     [ENOTDIR]		The from argument is not an absolute path and fromfd  is
			neither AT_FDCWD nor a file descriptor associated with a
			directory,  or	the  to argument is not an absolute path
			and tofd is neither AT_FDCWD nor a file descriptor asso-
			ciated with a directory.

CONFORMANCE
     The restriction on renaming a directory whose permissions disallow  writing
     is  based on the fact that UFS directories contain a ".." entry.  If renam-
     ing a directory would move it to another parent directory, this entry needs
     to be changed.

     This restriction has been generalized to disallow renaming  of  any  write-
     disabled  directory,  even when this would not require a change to the ".."
     entry.  For consistency, HFS+ directories emulate this behavior.

SEE ALSO
     open(2), symlink(7)

STANDARDS
     The rename() function conforms to IEEE Std  1003.1-1988  ("POSIX.1").   The
     renameat() system call is expected to conform to POSIX.1-2008 .

4.2 Berkeley Distribution      September 18, 2008		       RENAME(2)

home | help