*: moving files

1 files changed, 56 insertions, 0 deletions

diff --git a/man/duplex.2 b/man/duplex.2
new file mode 100644
index 0000000..192e72c
--- /dev/null
+++ b/man/duplex.2
@@ -0,0 +1,56 @@
+.Dd Jul 17, 2024
+.Dt DUPLEX 2
+.Os Camellia
+.Sh NAME
+.Nm duplex
+.Nd rename a file
+.Sh SYNOPSIS
+.In camellia/syscalls.h
+.Ft long
+.Fn _sys_duplex "hid_t from" "hid_t to" "int flags"
+.Sh DESCRIPTION
+.Nm
+is used for operations on two files or locations within the same filesystem
+\(em renames, links, etc.
+.Fa flags
+is a bitmask with the following options:
+.Bl -tag -width DUPLEX_REMOVE
+.It Dv DUPLEX_REMOVE
+Remove the source file after the operation \(em in other words, perform a move,
+instead of creating a new link.
+.El
+.Sh SEE ALSO
+.Xr open 2 ,
+.Xr rename 3
+.Sh BUGS
+.Xr rename 3 isn't atomic,
+as the destination file needs to be created before the duplex call.
+This could be fixed by having
+.Xr open 2
+accept a (hypothetical)
+.Dv OPEN_MOVETARGET
+flag.
+.Pp
+There are some cases where a
+.Nm
+call across different filesystems fails despite "making sense".
+.Sh RATIONALE
+Accepting two handles is the only sensible way to handle moving files,
+considering
+.Xr open 2 Ns 's
+role as a
+.Dq narrow waist .
+Having a generic
+.Nm
+call for all operations on two handles within a single filesystem seems to
+make sense.
+.Pp
+One other similar approach would be to have a way to send arbitrary handles
+to open files
+.Pq which I already plan to implement ,
+and to also have a syscall that can
+.Dq unwrap
+a handle controlled by the current process.
+Then that syscall would effectively be able to do everything
+.Nm
+can \(em but that seems more complex and awkward to use.