diff options
Diffstat (limited to 'man2/copy_file_range.2')
| -rw-r--r-- | man2/copy_file_range.2 | 307 |
1 files changed, 0 insertions, 307 deletions
diff --git a/man2/copy_file_range.2 b/man2/copy_file_range.2 deleted file mode 100644 index aee9801..0000000 --- a/man2/copy_file_range.2 +++ /dev/null @@ -1,307 +0,0 @@ -.\"This manpage is Copyright (C) 2015 Anna Schumaker <Anna.Schumaker@Netapp.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH copy_file_range 2 2023-10-31 "Linux man-pages 6.7" -.SH NAME -copy_file_range \- Copy a range of data from one file to another -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #define _GNU_SOURCE -.B #define _FILE_OFFSET_BITS 64 -.B #include <unistd.h> -.P -.BI "ssize_t copy_file_range(int " fd_in ", off_t *_Nullable " off_in , -.BI " int " fd_out ", off_t *_Nullable " off_out , -.BI " size_t " len ", unsigned int " flags ); -.fi -.SH DESCRIPTION -The -.BR copy_file_range () -system call performs an in-kernel copy between two file descriptors -without the additional cost of transferring data from the kernel to user space -and then back into the kernel. -It copies up to -.I len -bytes of data from the source file descriptor -.I fd_in -to the target file descriptor -.IR fd_out , -overwriting any data that exists within the requested range of the target file. -.P -The following semantics apply for -.IR off_in , -and similar statements apply to -.IR off_out : -.IP \[bu] 3 -If -.I off_in -is NULL, then bytes are read from -.I fd_in -starting from the file offset, and the file offset is -adjusted by the number of bytes copied. -.IP \[bu] -If -.I off_in -is not NULL, then -.I off_in -must point to a buffer that specifies the starting -offset where bytes from -.I fd_in -will be read. -The file offset of -.I fd_in -is not changed, but -.I off_in -is adjusted appropriately. -.P -.I fd_in -and -.I fd_out -can refer to the same file. -If they refer to the same file, then the source and target ranges are not -allowed to overlap. -.P -The -.I flags -argument is provided to allow for future extensions -and currently must be set to 0. -.SH RETURN VALUE -Upon successful completion, -.BR copy_file_range () -will return the number of bytes copied between files. -This could be less than the length originally requested. -If the file offset of -.I fd_in -is at or past the end of file, no bytes are copied, and -.BR copy_file_range () -returns zero. -.P -On error, -.BR copy_file_range () -returns \-1 and -.I errno -is set to indicate the error. -.SH ERRORS -.TP -.B EBADF -One or more file descriptors are not valid. -.TP -.B EBADF -.I fd_in -is not open for reading; or -.I fd_out -is not open for writing. -.TP -.B EBADF -The -.B O_APPEND -flag is set for the open file description (see -.BR open (2)) -referred to by the file descriptor -.IR fd_out . -.TP -.B EFBIG -An attempt was made to write at a position past the maximum file offset the -kernel supports. -.TP -.B EFBIG -An attempt was made to write a range that exceeds the allowed maximum file size. -The maximum file size differs between filesystem implementations and can be -different from the maximum allowed file offset. -.TP -.B EFBIG -An attempt was made to write beyond the process's file size resource limit. -This may also result in the process receiving a -.B SIGXFSZ -signal. -.TP -.B EINVAL -The -.I flags -argument is not 0. -.TP -.B EINVAL -.I fd_in -and -.I fd_out -refer to the same file and the source and target ranges overlap. -.TP -.B EINVAL -Either -.I fd_in -or -.I fd_out -is not a regular file. -.TP -.B EIO -A low-level I/O error occurred while copying. -.TP -.B EISDIR -Either -.I fd_in -or -.I fd_out -refers to a directory. -.TP -.B ENOMEM -Out of memory. -.TP -.B ENOSPC -There is not enough space on the target filesystem to complete the copy. -.TP -.BR EOPNOTSUPP " (since Linux 5.19)" -.\" commit 868f9f2f8e004bfe0d3935b1976f625b2924893b -The filesystem does not support this operation. -.TP -.B EOVERFLOW -The requested source or destination range is too large to represent in the -specified data types. -.TP -.B EPERM -.I fd_out -refers to an immutable file. -.TP -.B ETXTBSY -Either -.I fd_in -or -.I fd_out -refers to an active swap file. -.TP -.BR EXDEV " (before Linux 5.3)" -.\" commit 5dae222a5ff0c269730393018a5539cc970a4726 -The files referred to by -.IR fd_in " and " fd_out -are not on the same filesystem. -.TP -.BR EXDEV " (since Linux 5.19)" -.\" commit 868f9f2f8e004bfe0d3935b1976f625b2924893b -The files referred to by -.IR fd_in " and " fd_out -are not on the same filesystem, -and the source and target filesystems are not of the same type, -or do not support cross-filesystem copy. -.SH VERSIONS -A major rework of the kernel implementation occurred in Linux 5.3. -Areas of the API that weren't clearly defined were clarified and the API bounds -are much more strictly checked than on earlier kernels. -.P -Since Linux 5.19, -cross-filesystem copies can be achieved -when both filesystems are of the same type, -and that filesystem implements support for it. -See BUGS for behavior prior to Linux 5.19. -.P -Applications should target the behaviour and requirements of Linux 5.19, -that was also backported to earlier stable kernels. -.SH STANDARDS -Linux, GNU. -.SH HISTORY -Linux 4.5, -but glibc 2.27 provides a user-space -emulation when it is not available. -.\" https://sourceware.org/git/?p=glibc.git;a=commit;f=posix/unistd.h;h=bad7a0c81f501fbbcc79af9eaa4b8254441c4a1f -.SH NOTES -If -.I fd_in -is a sparse file, then -.BR copy_file_range () -may expand any holes existing in the requested range. -Users may benefit from calling -.BR copy_file_range () -in a loop, and using the -.BR lseek (2) -.B SEEK_DATA -and -.B SEEK_HOLE -operations to find the locations of data segments. -.P -.BR copy_file_range () -gives filesystems an opportunity to implement "copy acceleration" techniques, -such as the use of reflinks (i.e., two or more inodes that share -pointers to the same copy-on-write disk blocks) -or server-side-copy (in the case of NFS). -.P -.B _FILE_OFFSET_BITS -should be defined to be 64 in code that uses non-null -.I off_in -or -.I off_out -or that takes the address of -.BR copy_file_range , -if the code is intended to be portable -to traditional 32-bit x86 and ARM platforms where -.BR off_t 's -width defaults to 32 bits. -.SH BUGS -In Linux 5.3 to Linux 5.18, -cross-filesystem copies were implemented by the kernel, -if the operation was not supported by individual filesystems. -However, on some virtual filesystems, -the call failed to copy, while still reporting success. -.SH EXAMPLES -.\" SRC BEGIN (copy_file_range.c) -.EX -#define _GNU_SOURCE -#define _FILE_OFFSET_BITS 64 -#include <fcntl.h> -#include <stdio.h> -#include <stdlib.h> -#include <sys/stat.h> -#include <unistd.h> -\& -int -main(int argc, char *argv[]) -{ - int fd_in, fd_out; - off_t len, ret; - struct stat stat; -\& - if (argc != 3) { - fprintf(stderr, "Usage: %s <source> <destination>\en", argv[0]); - exit(EXIT_FAILURE); - } -\& - fd_in = open(argv[1], O_RDONLY); - if (fd_in == \-1) { - perror("open (argv[1])"); - exit(EXIT_FAILURE); - } -\& - if (fstat(fd_in, &stat) == \-1) { - perror("fstat"); - exit(EXIT_FAILURE); - } -\& - len = stat.st_size; -\& - fd_out = open(argv[2], O_CREAT | O_WRONLY | O_TRUNC, 0644); - if (fd_out == \-1) { - perror("open (argv[2])"); - exit(EXIT_FAILURE); - } -\& - do { - ret = copy_file_range(fd_in, NULL, fd_out, NULL, len, 0); - if (ret == \-1) { - perror("copy_file_range"); - exit(EXIT_FAILURE); - } -\& - len \-= ret; - } while (len > 0 && ret > 0); -\& - close(fd_in); - close(fd_out); - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.SH SEE ALSO -.BR lseek (2), -.BR sendfile (2), -.BR splice (2) |