Differential D27935 Diff 81563 lib/libc/sys/copy_file_range.2

Changeset 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 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			.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
				asomersUnsubmitted Done Inline Actions I think this belongs in the DESCRIPTION section, not RETURN VALUES. 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
				asomersUnsubmitted Not Done Inline Actions Why 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 Actions Because it returns ssize_t. I didn't think that needed to be stated here, but if you think it should be, I can add a sentence. 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 Actions Ahh, that makes sense. asomers: Ahh, that makes sense.
	The			The
	.Fn copy_file_range			.Fn copy_file_range
				asomersUnsubmitted Done Inline Actions I 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			.Fa
	infd			infd
	is not open for reading or			is not open for reading or
	▲ Show 20 Lines • Show All 58 Lines • Show Last 20 Lines