Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

14.7 Renaming Files

The rename function is used to change a file's name.

— Function: int rename (const char *oldname, const char *newname)

The rename function renames the file oldname to newname. The file formerly accessible under the name oldname is afterwards accessible as newname instead. (If the file had any other names aside from oldname, it continues to have those names.)

The directory containing the name newname must be on the same file system as the directory containing the name oldname.

One special case for rename is when oldname and newname are two names for the same file. The consistent way to handle this case is to delete oldname. However, in this case POSIX requires that rename do nothing and report success—which is inconsistent. We don't know what your operating system will do.

If oldname is not a directory, then any existing file named newname is removed during the renaming operation. However, if newname is the name of a directory, rename fails in this case.

If oldname is a directory, then either newname must not exist or it must name a directory that is empty. In the latter case, the existing directory named newname is deleted first. The name newname must not specify a subdirectory of the directory oldname which is being renamed.

One useful feature of rename is that the meaning of newname changes “atomically” from any previously existing file by that name to its new meaning (i.e. the file that was called oldname). There is no instant at which newname is non-existent “in between” the old meaning and the new meaning. If there is a system crash during the operation, it is possible for both names to still exist; but newname will always be intact if it exists at all.

If rename fails, it returns -1. In addition to the usual file name errors (see File Name Errors), the following errno error conditions are defined for this function:

EACCES
One of the directories containing newname or oldname refuses write permission; or newname and oldname are directories and write permission is refused for one of them.
EBUSY
A directory named by oldname or newname is being used by the system in a way that prevents the renaming from working. This includes directories that are mount points for filesystems, and directories that are the current working directories of processes.
ENOTEMPTY
EEXIST
The directory newname isn't empty. The GNU system always returns ENOTEMPTY for this, but some other systems return EEXIST.
EINVAL
oldname is a directory that contains newname.
EISDIR
newname is a directory but the oldname isn't.
EMLINK
The parent directory of newname would have too many links (entries).
ENOENT
The file oldname doesn't exist.
ENOSPC
The directory that would contain newname has no room for another entry, and there is no space left in the file system to expand it.
EROFS
The operation would involve writing to a directory on a read-only file system.
EXDEV
The two file names newname and oldname are on different file systems.


 
 
  Published under the terms of the GNU General Public License Design by Interspire