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: head/lib/libc/sys/copy_file_range.2 359465 2020-03-30 21:44:00Z jhb $ | .\" $FreeBSD: head/lib/libc/sys/copy_file_range.2 359465 2020-03-30 21:44:00Z jhb $ | ||||
.\" | .\" | ||||
.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 91 Lines • ▼ Show 20 Lines | |||||
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. | ||||
For performance reasons, the | |||||
asomers: I think this belongs in the DESCRIPTION section, not RETURN VALUES. | |||||
.Fa len | |||||
argument should be set to the largest value possible. | |||||
For copying to EOF on the input file, the value may be SSIZE_MAX. | |||||
asomersUnsubmitted 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 ? | |||||
rmacklemAuthorUnsubmitted 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… | |||||
asomersUnsubmitted Not Done Inline ActionsAhh, that makes sense. asomers: Ahh, that makes sense. | |||||
Doing so reduces the number of system calls, along with | |||||
associated SEEK_HOLE, SEEK_DATA operations done either by | |||||
asomersUnsubmitted 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… | |||||
.Xr lseek 2 | |||||
or internally by | |||||
.Fn copy_file_range . | |||||
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 | ||||
the global variable | the global variable | ||||
.Va errno . | .Va errno . | ||||
.Sh ERRORS | .Sh ERRORS | ||||
The | The | ||||
.Fn copy_file_range | .Fn copy_file_range | ||||
system call | system call | ||||
will fail if: | will fail if: | ||||
▲ Show 20 Lines • Show All 64 Lines • Show Last 20 Lines |
I think this belongs in the DESCRIPTION section, not RETURN VALUES.