Re: [patch] sendfile.2: Document the correct required syscall for offsets

Re: [patch] sendfile.2: Document the correct required syscall for offsets

[Michael Kerrisk (man-pages)]

Hello Joseph,

On 9/2/18 10:56 PM, Joseph C. Sible wrote:
> There's not even any such syscall as "seek". (There is an "lseek",
> but it's not correct here either.) The do_sendfile function in
> fs/read_write.c tests for FMODE_PREAD before erroring with -ESPIPE,
> so it's actually pread() that's required to work to use an offset.
> ---
>  man2/sendfile.2 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man2/sendfile.2 b/man2/sendfile.2
> index 4f85fdb..f316319 100644
> --- a/man2/sendfile.2
> +++ b/man2/sendfile.2
> @@ -165,7 +165,7 @@ the input file or the output file.
>  .B ESPIPE
>  .I offset
>  is not NULL but the input file is not
> -.BR seek (2)-able.
> +.BR pread (2)-able.
>  .SH VERSIONS
>  .BR sendfile ()
>  first appeared in Linux 2.2.

I'm not completely sure of the difference between FMODE_PREAD
and "seekable", but the point is that in terms of what users
understand, what is relevant here is "seekable" (as even stated
in the pread(2) manual page).

I applied the patch below. But if you can show me a meaningful
difference between FMODE_PREAD and "seekable", I'd be happy
to further update the text.

Cheers,

Michael

diff --git a/man2/sendfile.2 b/man2/sendfile.2
index 4f85fdbd7..f0ead4a9b 100644
--- a/man2/sendfile.2
+++ b/man2/sendfile.2
@@ -164,8 +164,7 @@ the input file or the output file.
 .TP
 .B ESPIPE
 .I offset
-is not NULL but the input file is not
-.BR seek (2)-able.
+is not NULL but the input file is not seekable.
 .SH VERSIONS
 .BR sendfile ()
 first appeared in Linux 2.2.


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/