# ioctl_xfs_exchange_range

## NAME



           ioctl_xfs_exchange_range - exchange the contents of parts of two
           files
    


## 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



           Given 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) exchanges the
           contents of the two ranges.
    
           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.
    
           The system call parameters are conveyed in structures of the
           following form:
    
               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.
    
           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.  If the two
           file descriptors represent the same file, the byte ranges must not
           overlap.  Most disk-based filesystems require that the starts of
           both ranges must be aligned to the file block size.  If this is
           the case, the ends of the ranges must also be so aligned unless
           the **XFS_EXCHANGE_RANGE_TO_EOF** flag is set.
    
           The field _flags_ control the behavior of the exchange operation.
    
               **XFS_EXCHANGE_RANGE_TO_EOF**
                      Ignore the _length_ parameter.  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_)).
    
               **XFS_EXCHANGE_RANGE_DSYNC**
                      Ensure 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.  Opening either file
                      descriptor with **O_SYNC** or **O_DSYNC** will have the same
                      effect.
    
               **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 if all writes are
                      aligned to the file allocation unit.
    
               **XFS_EXCHANGE_RANGE_DRY_RUN**
                      Check the parameters and the feasibility of the
                      operation, but do not change anything.
    


## RETURN VALUE



           On error, -1 is returned, and _errno_ is set to indicate the error.
    


## ERRORS



           Error codes can be one of, but are not limited to, the following:
    
           **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.
    
           **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.
    
           **EIO** An I/O error occurred.
    
           **EISDIR** One of the files is a directory.
    
           **ENOMEM** The kernel was unable to allocate sufficient memory to
                  perform the operation.
    
           **ENOSPC** There is not enough free space in the filesystem exchange
                  the contents safely.
    
           **EOPNOTSUPP**
                  The filesystem does not support exchanging bytes between
                  the two files.
    
           **EPERM** _file1_fd_ or _file2_fd_ are immutable.
    
           **ETXTBSY**
                  One of the files is a swap file.
    
           **EUCLEAN**
                  The filesystem is corrupt.
    
           **EXDEV** _file1_fd_ and _file2_fd_ are not on the same mounted
                  filesystem.
    


## CONFORMING TO



           This API is XFS-specific.
    


## 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.
    
           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.
    
           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);
    
           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.
    
           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.
    


* * *