Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/sys/copy_file_range.2
Show All 19 Lines | |||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd March 30, 2020 | .Dd January 2, 2021 | ||||
.Dt COPY_FILE_RANGE 2 | .Dt COPY_FILE_RANGE 2 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm copy_file_range | .Nm copy_file_range | ||||
.Nd kernel copy of a byte range from one file to another | .Nd kernel copy of a byte range from one file to another | ||||
or within one file | or within one file | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libc | .Lb libc | ||||
▲ Show 20 Lines • Show All 75 Lines • ▼ Show 20 Lines | |||||
However, this does not always work well. | However, this does not always work well. | ||||
It is recommended that sparse files be copied in a loop using | It is recommended that sparse files be copied in a loop using | ||||
.Xr lseek 2 | .Xr lseek 2 | ||||
with | with | ||||
.Dv SEEK_HOLE , | .Dv SEEK_HOLE , | ||||
.Dv SEEK_DATA | .Dv SEEK_DATA | ||||
arguments and this system call for the | arguments and this system call for the | ||||
data ranges found. | data ranges found. | ||||
.Pp | |||||
For best performance, call | |||||
.Fn copy_file_range | |||||
with the largest | |||||
.Fa len | |||||
value possible. | |||||
It is interruptible on most file systems, | |||||
so there is no penalty for using very large len values, even SSIZE_MAX. | |||||
.Pp | |||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
If it succeeds, the call returns the number of bytes copied, which can be fewer | If it succeeds, the call returns the number of bytes copied, which can be fewer | ||||
than | than | ||||
.Fa len . | .Fa len . | ||||
Returning fewer bytes than | Returning fewer bytes than | ||||
.Fa len | .Fa len | ||||
does not necessarily indicate that EOF was reached. | does not necessarily indicate that EOF was reached. | ||||
However, a return of zero for a non-zero | However, a return of zero for a non-zero | ||||
.Fa len | .Fa len | ||||
argument indicates that the offset for | argument indicates that the offset for | ||||
.Fa infd | .Fa infd | ||||
is at or beyond EOF. | is at or beyond EOF. | ||||
.Fn copy_file_range | .Fn copy_file_range | ||||
should be used in a loop until copying of the desired byte range has been | should be used in a loop until copying of the desired byte range has been | ||||
completed. | completed. | ||||
If an error has occurred, a \-1 is returned and the error code is placed in | If an error has occurred, a \-1 is returned and the error code is placed in | ||||
asomers: I think this belongs in the DESCRIPTION section, not RETURN VALUES. | |||||
the global variable | the global variable | ||||
.Va errno . | .Va errno . | ||||
.Sh ERRORS | .Sh ERRORS | ||||
Not Done Inline ActionsWhy SSIZE_MAX? Since len is defined as a size_t, shouldn't the limit be SIZE_MAX ? asomers: Why SSIZE_MAX? Since len is defined as a size_t, shouldn't the limit be SIZE_MAX ? | |||||
Done Inline ActionsBecause it returns ssize_t. rmacklem: Because it returns ssize_t.
I didn't think that needed to be stated here,
but if you think it… | |||||
Not Done Inline ActionsAhh, that makes sense. asomers: Ahh, that makes sense. | |||||
The | The | ||||
.Fn copy_file_range | .Fn copy_file_range | ||||
Done Inline ActionsI think this qualifies as TMI. I might phrase it as "For best performance, call copy_file_range with the largest len value possible. It is interruptible on most file systems, so there is no penalty for using very large len values, even SSIZE_MAX." asomers: I think this qualifies as TMI. I might phrase it as "For best performance, call… | |||||
system call | system call | ||||
will fail if: | will fail if: | ||||
.Bl -tag -width Er | .Bl -tag -width Er | ||||
.It Bq Er EBADF | .It Bq Er EBADF | ||||
If | If | ||||
.Fa infd | .Fa infd | ||||
is not open for reading or | is not open for reading or | ||||
.Fa outfd | .Fa outfd | ||||
▲ Show 20 Lines • Show All 55 Lines • Show Last 20 Lines |
I think this belongs in the DESCRIPTION section, not RETURN VALUES.