Rename

Rename a directory or file

Rename() attempts to rename the file or directory specified as 'oldName' with the name 'newName'. If the file or directory 'newName' exists, Rename() fails and returns an error. Both 'oldName' and the 'newName' can contain a directory specification, i.e. path and directory names such as "volume:directory/file". In this case, the file will be moved from one directory to another.

oldName

pointer to a null-terminated string

newName

pointer to a null-terminated string

success

boolean; FALSE for failure, call IoErr() to find out why Rename() has failed.

The Amiga ROM file system as well as the RAM: file system will truncate path and file names to the maximum supported length instead of rejecting an overly long name with an error. Hence, a file with the unlikely name of "supercalifragilisticexpialidocious" (34 characters) may be considered identical to "supercalifragilisticexpialidoc" (30 characters).

There is a certain risk that by trying to rename a file whose name exceeds the maximum name length will end up moving it into a directory whose name is a truncated form when you expected only its name to be changed.

A possible workaround to detect the risk of accidentally moving a file into a directory involves the use of the SameLock() function. Begin by obtaining Locks on the "supercalifragilisticexpialidocious.info" icon file and its associated "supercalifragilisticexpialidocious" file. If you can obtain both locks, then these might refer to the same file: SameLock() will return LOCK_DIFFERENT. If these are different directory entries, check if the destination is what you expected, i.e. if you wanted to move a file or directory into a different directory, the destination Lock should refer to a directory, and not a file.

It is impossible to Rename() a file from one volume to another.

Relabel(), IoErr()