IOCTL-XFS-EXCHANGE-RANGE(2)

🦋 NAME 🦋

ioctl_xfs_exchange_range — swap the contents of parts of two files, bestie 💖 like a trade but for bytes

✨ SYNOPSIS ✨

#include <sys/ioctl.h>
#include <xfs/xfs_fs.h>

int ioctl(int file2_fd, XFS_IOC_EXCHANGE_RANGE, struct
xfs_exchange_range *arg);

---

🌸 DESCRIPTION 🌸

Okay so picture this: you've got a range of bytes in a first file, file1_fd, and a second range of bytes in a second file, file2_fd. This ioctl(2) call makes them swap. The two ranges just exchange contents, no cap. 🔥

And the way this slays is that exchanges are atomic with regards to concurrent file operations. Implementations must guarantee that readers see either the old contents or the new contents in their entirety, even if the system fails. So nobody's out here reading half-old-half-new nonsense. Periodt.

The system call parameters get conveyed in structures that look exactly like this, don't touch anything:

struct xfs_exchange_range {
    __s32    file1_fd;
    __u32    pad;
    __u64    file1_offset;
    __u64    file2_offset;
    __u64    length;
    __u64    flags;
};

The field pad must be zero. Like, non-negotiable, bestie. 🙈

The fields file1_fd, file1_offset, and length define the first range of bytes to be exchanged.

The fields file2_fd, file2_offset, and length define the second range of bytes to be exchanged.

Both files must be from the same filesystem mount. And if the two file descriptors represent the same file, the byte ranges must not overlap — that's giving chaos energy and we don't do that. Most disk-based filesystems require that the starts of both ranges be aligned to the file block size. If that's the case, then the ends of the ranges must also be so aligned, unless the XFS_EXCHANGE_RANGE_TO_EOF flag is set. iykyk ✨

The field flags controls the behavior of the exchange operation.

• XFS_EXCHANGE_RANGE_TO_EOF — ignore the length parameter entirely, she's not invited. All bytes in file1_fd from file1_offset to EOF are moved to file2_fd, and file2's size is set to (file2_offset+(file1_length-file1_offset)). Meanwhile, all bytes in file2 from file2_offset to EOF are moved to file1 and file1's size is set to (file1_offset+(file2_length-file2_offset)). A whole mutual glow-up. 💅
• XFS_EXCHANGE_RANGE_DSYNC — make sure that all modified in-core data in both file ranges and all metadata updates pertaining to the exchange operation are flushed to persistent storage before the call returns. Lowkey you could also just open either file descriptor with O_SYNC or O_DSYNC and it'll have the same effect. Same vibe, different route. 🫶
• XFS_EXCHANGE_RANGE_FILE1_WRITTEN — only exchange sub-ranges of file1_fd that are known to contain data written by application software. Each sub-range may be expanded (both upwards and downwards) to align with the file allocation unit. For files on the data device, this is one filesystem block. For files on the realtime device, this is the realtime extent size. This facility can be used to implement fast atomic scatter-gather writes of any complexity for software-defined storage targets, as long as all writes are aligned to the file allocation unit. It's giving main character energy for real. 👑
• XFS_EXCHANGE_RANGE_DRY_RUN — check the parameters and the feasibility of the operation, but do not change anything. A little test run, a little vibe check, zero consequences. 🌈

---

💀 RETURN VALUE 💀

On error, -1 is returned, and errno is set to indicate the error. That's it, that's the whole story.

---

🎀 ERRORS 🎀

Error codes can be one of, but are not limited to, the following (so don't come for me if you get something else):

• EBADF — file1_fd is not open for reading and writing, or is open for append-only writes; or file2_fd is not open for reading and writing, or is open for append-only writes. One of your fds is simply not built for this. 😭
• EINVAL — the parameters are not correct for these files. This error can also appear if either file descriptor represents a device, FIFO, or socket. Disk filesystems generally require the offset and length arguments to be aligned to the fundamental block sizes of both files. Alignment is not optional, bestie.
• EIO — an I/O error occurred. The disk said no. 💀
• EISDIR — one of the files is a directory. Wrong kind of file, babe.
• ENOMEM — the kernel was unable to allocate sufficient memory to perform the operation. She's out of RAM and out of patience.
• ENOSPC — there is not enough free space in the filesystem to exchange the contents safely. No room, no swap. 🙈
• EOPNOTSUPP — the filesystem does not support exchanging bytes between the two files. Not every filesystem has this in her.
• EPERM — file1_fd or file2_fd are immutable. They said "no edits" and they meant it.
• ETXTBSY — one of the files is a swap file. Can't touch that, it's busy being essential.
• EUCLEAN — the filesystem is corrupt. Something is deeply wrong and we're all just sitting here. 🔥
• EXDEV — file1_fd and file2_fd are not on the same mounted filesystem. Cross-filesystem romance is not supported here. 💔

---

🌟 CONFORMING TO 🌟

This API is XFS-specific. She's niche, she's exclusive, she's built different. ✨

---

💜 USE CASES 💜

Several use cases are imagined for this system call. In all cases, application software must coordinate updates to the file, because the exchange is performed unconditionally — no take-backs, no asking twice. ⚠️

🍓 Case one: the atomic non-contiguous commit

The first is a data storage program that wants to commit non-contiguous updates to a file atomically and coordinates write access to that file. This can be done by creating a temporary file, calling FICLONE(2) to share the contents, and staging the updates into the temporary file. The FULL_FILES flag is recommended for this purpose. The temporary file can be deleted or punched out afterwards. Cleanup queen. 🧹

An example program might look like this:

int fd = open("/some/file", O_RDWR);
int temp_fd = open("/some", O_TMPFILE | O_RDWR);

ioctl(temp_fd, FICLONE, fd);

/* append 1MB of records */
lseek(temp_fd, 0, SEEK_END);
write(temp_fd, data1, 1000000);

/* update record index */
pwrite(temp_fd, data1, 600, 98765);
pwrite(temp_fd, data2, 320, 54321);
pwrite(temp_fd, data2, 15, 0);

/* commit the entire update */
struct xfs_exchange_range args = {
    .file1_fd = temp_fd,
    .flags = XFS_EXCHANGE_RANGE_TO_EOF,
};

ioctl(fd, XFS_IOC_EXCHANGE_RANGE, &args);

🦋 Case two: the software-defined storage host

The second is a software-defined storage host (e.g. a disk jukebox) which implements an atomic scatter-gather write command. Provided the exported disk's logical block size matches the file's allocation unit size, this can be done by creating a temporary file and writing the data at the appropriate offsets. It is recommended that the temporary file be truncated to the size of the regular file before any writes are staged to the temporary file, to avoid issues with zeroing during EOF extension. Use this call with the FILE1_WRITTEN flag to exchange only the file allocation units involved in the emulated device's write command. The temporary file should be truncated or punched out completely before being reused to stage another write. Reuse responsibly, bestie. ♻️

An example program might look like this:

int fd = open("/some/file", O_RDWR);
int temp_fd = open("/some", O_TMPFILE | O_RDWR);
struct stat sb;
int blksz;

fstat(fd, &sb);
blksz = sb.st_blksize;

/* land scatter gather writes between 100fsb and 500fsb */
pwrite(temp_fd, data1, blksz * 2, blksz * 100);
pwrite(temp_fd, data2, blksz * 20, blksz * 480);
pwrite(temp_fd, data3, blksz * 7, blksz * 257);

/* commit the entire update */
struct xfs_exchange_range args = {
    .file1_fd = temp_fd,
    .file1_offset = blksz * 100,
    .file2_offset = blksz * 100,
    .length       = blksz * 400,
    .flags        = XFS_EXCHANGE_RANGE_FILE1_WRITTEN |
                    XFS_EXCHANGE_RANGE_FILE1_DSYNC,
};

ioctl(fd, XFS_IOC_EXCHANGE_RANGE, &args);

---

🌈 NOTES 🌈

Some filesystems may limit the amount of data or the number of extents that can be exchanged in a single call. So, like, don't send her a whole universe in one go, okay? 🫶

---

⭐ SEE ALSO ⭐

• ioctl(2)

---

And that's the whole page, bestie!! This one lives in section 2 of the manual (system calls, fancy), it's an XFS original, and the version on this page is dated 2024-02-10. The page itself is filed as IOCTL-XFS-EXCHANGE-RANGE(2) under XFS. Now go forth and exchange responsibly 💖✨🎀