The description of SPLICE_F_GIFT explains what happens when the flag is specified, but it was unclear to whether data spliced into the pipe with vmsplice, but without SPLICE_F_GIFT, is copied immediately or simply mapped into the kernel and copied by splice(2) SPLICE_F_MOVE later. Tests and kernel code reveal that vmsplice(2) maps the memory into the kernel and it is copied later; this means applications can't e.g. free the memory after a successful call to vmsplice(2) even when they omit the SPLICE_F_GIFT flag. Signed-off-by: Joe Damato <jdamato@xxxxxxxxxx> --- man2/vmsplice.2 | 36 +++++++++++++++++++++++++++++++----- 1 file changed, 31 insertions(+), 5 deletions(-) diff --git a/man2/vmsplice.2 b/man2/vmsplice.2 index 9102c4c..b96bcc6 100644 --- a/man2/vmsplice.2 +++ b/man2/vmsplice.2 @@ -116,17 +116,43 @@ otherwise the page cache and on-disk data may differ. Gifting pages to the kernel means that a subsequent .BR splice (2) .B SPLICE_F_MOVE -can successfully move the pages; -if this flag is not specified, then a subsequent -.BR splice (2) -.B SPLICE_F_MOVE -must copy the pages. +can successfully move the pages. Data must also be properly page aligned, both in memory and length. .\" FIXME .\" It looks like the page-alignment requirement went away with .\" commit bd1a68b59c8e3bce45fb76632c64e1e063c3962d .\" .\" .... if we expect to later SPLICE_F_MOVE to the cache. + +If +.B SPLICE_F_GIFT +is not specified, the kernel will still map +the memory into +.I fd. +No copy is made during the invocation of +.BR vmsplice (2) +itself and so the application must take care when modifying the data after +successful calls to +.BR vmsplice(2). +Subsequent +.BR splice (2) +.B SPLICE_F_MOVE +will make a copy of the data that was mapped into +.I fd +during +.BR vmsplice (2). +Thus, any modifications to the memory after a successful call to +.BR vmsplice(2) +will appear when +.BR splice(2) +.B SPLICE_F_MOVE +generates its copy. +Once usage of +.BR splice(2) +is complete and the pipe is closed, the application will be the only user +of the data and can freely modify the data as needed (e.g. by +overwriting it, releasing the memory to the allocator, etc). + .SH RETURN VALUE Upon successful completion, .BR vmsplice () -- 2.7.4
