Function

rename invokes the rename callable service to change the name of a file or directory.

Parameters

old_pathname

An existing pathname.

new_pathname

A new pathname.

Usage notes

The rename service changes the name of a file or directory from old_pathname to new_pathname. When renaming finishes successfully, the change and modification times for the parent directories of old_pathname and new_pathname are updated.

The calling process needs write permission for the directory containing old_pathname and the directory containing new_pathname. The caller does not need write permission for the files themselves.

Renaming files: If old_pathname and new_pathname are links referring to the same file, rename returns successfully.

If old_pathname is the name of a file, new_pathname must also name a file, not a directory. If new_pathname is an existing file, it is unlinked. Then the file specified as old_pathname is given new_pathname. The pathname new_pathname always stays in existence; at the beginning of the operation, new_pathname refers to its original file, and at the end, it refers to the file that used to be old_pathname.

Renaming directories: If old_pathname is the name of a directory, new_pathname must also name a directory, not a file. If new_pathname is an existing directory, it must be empty, containing no files or subdirectories. If empty, it is removed, as described in rmdir.

new_pathname cannot be a directory under old_pathname; that is, the old directory cannot be part of the pathname prefix of the new one.