Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
RENAME(2)		   Linux Programmer's Manual		     RENAME(2)

       rename -	change the name	or location of a file

       #include	<stdio.h>

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

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

       Any  other  hard	links to the file (as created using link(2)) are unaf-

       If newpath already exists it will be atomically replaced	(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 rename	 guar-
       antees 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.

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

       EISDIR newpath is an existing directory,	but oldpath is	not  a	direc-

       EXDEV  oldpath and newpath are not on the same filesystem.

	      newpath  is  a non-empty directory, i.e.,	contains entries other
	      than "." and "..".

       EBUSY  The rename fails because oldpath or newpath is a directory  that
	      is in use	by some	process	(perhaps as current working directory,
	      or as root directory, or because it was open for reading)	or  is
	      in  use  by  the	system (for example as mount point), while the
	      system considers this an error.  (Note that there	is no require-
	      ment to return EBUSY in such cases - there is nothing wrong with
	      doing the	rename anyway -	but it is allowed to return  EBUSY  if
	      the system cannot	otherwise handle such situations.)

       EINVAL The  new	pathname  contained a path prefix of the old, or, more
	      generally, an attempt was	made to	make a directory  a  subdirec-
	      tory of itself.

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

	      A	component used as a directory in oldpath or newpath is not, in
	      fact, a directory.  Or, oldpath is a directory, and newpath  ex-
	      ists but is not 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 effective uid, or one of  the  di-
	      rectories	 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 or	EACCES
	      The  directory containing	oldpath	has the	sticky bit set and the
	      process's	effective uid is neither that of root nor the  uid  of
	      the  file	to be deleted nor that of the directory	containing it,
	      or newpath is an existing	file and the directory	containing  it
	      has  the	sticky bit set and the process's effective uid is nei-
	      ther that	of root	nor the	uid of the file	 to  be	 replaced  nor
	      that  of the directory containing	it, or the filesystem contain-
	      ing pathname does	not support renaming of	the type requested.

	      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  Too many symbolic	links were encountered in resolving oldpath or

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

       POSIX, 4.3BSD, ANSI C

       On NFS filesystems, you can not assume that if 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.

       link(2),	unlink(2), symlink(2), mv(1)

Linux 2.0			  1998-06-04			     RENAME(2)


Want to link to this manual page? Use this URL:

home | help