f_rename

The f_rename function renames and/or moves a file or sub-directory.

FRESULT f_rename (
  const TCHAR* old_name, /* [IN] Old object name */
  const TCHAR* new_name  /* [IN] New object name */
);

Parameters

old_name
Pointer to the null-terminated string that specifies the existing file or sub-directory to be renamed.
new_name
Pointer to the null-terminated string that specifies the new object name. A drive number may be specified in this string but it is ignored and assumed as the same drive of the old_name. Any object with this name except old_name must not be exist, or the function fails with FR_EXIST.

Return Values

FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_FILE, FR_NO_PATH, FR_INVALID_NAME, FR_EXIST, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_LOCKED, FR_NOT_ENOUGH_CORE

Description

Renames a file or sub-directory and can also move it to another directory in the same volume. The file to be renamed must not be an open file, or the FAT volume can be collapsed. Such the wrong file renaming is rejected safely when file lock function is enabled.

Any sub-directory in the current directory path should not be renamed. It will be rejected on the exFAT volume but succeeds on the FAT/FAT32 volume.

Remark: Be careful in moving a sub-directory. The sub-directory must not be moved into itself and any sub-directory in it, or the moved sub-directory will be lost.

QuickInfo

Available when FF_FS_READONLY == 0 and FF_FS_MINIMIZE == 0.

Example

    /* Rename an object in the default drive */
    f_rename("oldname.txt", "newname.txt");

    /* Rename an object in the drive 2 */
    f_rename("2:oldname.txt", "newname.txt");

    /* Rename an object and move it into another directory in the drive */
    f_rename("log.txt", "old/log0001.txt");

Return