fs: fat: add rename

The implementation roughly follows the POSIX specification for
rename() [1]. The ordering of operations attempting to minimize the chance
for data loss in unexpected circumstances.

The 'mv' command was implemented as a front end for the rename operation
as that is what most users are likely familiar with in terms of behavior.

The 'FAT_RENAME' Kconfig option was added to prevent code size increase on
size-oriented builds like SPL.

[1] https://pubs.opengroup.org/onlinepubs/9799919799/functions/rename.html

Signed-off-by: Gabriel Dalimonte <gabriel.dalimonte@gmail.com>

1 files changed, 61 insertions, 0 deletions

diff --git a/doc/usage/cmd/mv.rst b/doc/usage/cmd/mv.rst
new file mode 100644
index 00000000000..99864371038
--- /dev/null
+++ b/doc/usage/cmd/mv.rst
@@ -0,0 +1,61 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+.. index::
+   single: mv (command)
+
+mv command
+==========
+
+Synopsis
+--------
+
+::
+
+    mv <interface> [<dev[:part]>] <old_path> <new_path>
+
+Description
+-----------
+
+The mv command renames/moves a file or directory within a filesystem.
+
+interface
+    interface for accessing the block device (mmc, sata, scsi, usb, ....)
+
+dev
+    device number
+
+part
+    partition number, defaults to 0 (whole device)
+
+old_path
+   existing path to file/directory
+
+new_path
+   new path/name for the rename/move
+
+
+Example
+-------
+
+    # Rename file 'foo' in directory 'dir' to 'bar'
+    mv mmc 0:0 dir/foo dir/bar
+
+    # Move file 'f' from directory 'foo' to existing directory 'bar' renaming
+    # 'f' to 'g'
+    mv mmc 0:0 foo/f bar/g
+
+    # Move directory 'abc' in directory 'dir1' into existing directory 'dir2'
+    mv mmc 0:0 dir1/abc dir2
+
+Configuration
+-------------
+
+The mv command is only available if CONFIG_CMD_FS_GENERIC=y.
+
+Return value
+------------
+
+The return value $? is set to 0 (true) if the file was successfully
+renamed/moved.
+
+If an error occurs, the return value $? is set to 1 (false).