*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Linux man pages -> rename (2)              



NAME    [Toc]    [Back]

       rename - change the name or location of a file

SYNOPSIS    [Toc]    [Back]

       #include <stdio.h>

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

DESCRIPTION    [Toc]    [Back]

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

       Any  other  hard links to the file (as created using link(2)) are unaffected.

       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  guarantees
 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.

RETURN VALUE    [Toc]    [Back]

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

ERRORS    [Toc]    [Back]

       EISDIR newpath is an existing directory, but oldpath is	not  a	directory.

       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 requirement
 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  subdirectory
 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.

       ENOTDIR    [Toc]    [Back]
	      A component used as a directory in oldpath or newpath is not, in
	      fact, a directory.  Or, oldpath  is  a  directory,  and  newpath
	      exists 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
	      directories 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  neither
  that  of  root  nor the uid of the file to be replaced nor
	      that of the directory containing it, or the filesystem  containing
 pathname does not support renaming of the type requested.

       ENAMETOOLONG    [Toc]    [Back]
	      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

CONFORMING TO    [Toc]    [Back]

       POSIX, 4.3BSD, ANSI C

BUGS    [Toc]    [Back]

       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.

SEE ALSO    [Toc]    [Back]

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

Linux 2.0			  1998-06-04			     RENAME(2)
[ Back ]
 Similar pages
Name OS Title
mvView IRIX Change the location and size of the region for movie display inside a GL window
AFseekframe IRIX move logical file read pointer for a specified audio track to a desired sample frame location / retrieve curre
chattr Linux change file attributes on a Linux second extended file system
rename OpenBSD change the name of a file
rename IRIX change the name of a file
rename NetBSD change the name of a file
rename HP-UX change the name of a file
rename FreeBSD change the name of a file
chmod Linux change permissions of a file
chlabel IRIX change the label of a file
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service