Re: Man page doc for SEEK_DATA/SEEK_HOLE

[Sunil Mushran <sunil.mushran@oracle.com>]

On 09/18/2011 12:07 AM, Michael Kerrisk wrote:
> Hello Josef,
>
> For Linux 3.1, you've added SEEK_HOLE + SEEK_DATA. I've attempted to
> document these as below for the lseek.2 man page. Could you please
> review?
>
> Thanks,
>
> Michael
>
>
> diff --git a/man2/lseek.2 b/man2/lseek.2
> index 26943e2..941ea08 100644
> --- a/man2/lseek.2
> +++ b/man2/lseek.2
> @@ -85,6 +85,69 @@ of the file (but this does not change the size of the file).
>   If data is later written at this point, subsequent reads of the data
>   in the gap (a "hole") return null bytes (\(aq\\0\(aq) until
>   data is actually written into the gap.
> +.SS Seeking file data and holes
> +Since version 3.1, Linux supports the following additional values for
> +.IR whence :
> +.TP
> +.B SEEK_DATA
> +Adjust the file offset to the next region
> +in the file greater than or equal to
> +.I offset

I would recommend dropping the word next as it is confusing considering the
offset returned could be the offset passed in.

> +containing data.
> +If
> +.I offset
> +points to data,
> +then the file offset is set to
> +.IR offset .
> +.TP
> +.B SEEK_HOLE
> +Adjust the file offset to the next hole in the file
> +greater than or equal to
> +.IR offset .

Same here.

> +If
> +.I offset
> +points into the middle of a hole,
> +then the file offset is set to
> +.IR offset .
> +If there is no hole past
> +.IR offset ,
> +then the file offset is adjusted to the end of the file
> +(i.e., there is an implicit hole at the end of any file).
> +.PP
> +In both of the above cases,
> +.BR lseek ()
> +fails if
> +.I offset
> +points past the end of the file.
> +
> +These operations allow applications to map holes in a sparsely
> +allocated file.
> +This can be useful for applications such as file backup tools,
> +which can save space when creating backups and preserve holes,
> +if they have a mechanism for discovering holes.
> +
> +For the purposes of these operations, a hole is a sequence of zeroes that
> +(normally) has not been allocated in the underlying file storage.
> +However, a file system is not obliged to report holes,
> +so these operations are not a guaranteed mechanism for
> +mapping the storage space actually allocated to a file.
> +(Furthermore, a sequence of zeroes that actually has been written
> +to the underlying storage normally won't be reported as a hole.)

Instead of "won't be", make it "may not be". The interface should not limit
the file system/block device.

> +In the simplest implementation,
> +a file system can support the operations by making
> +.BR SEEK_HOLE
> +always return the offset of the end of the file,
> +and making
> +.BR SEEK_DATA
> +always return
> +return
> +.IR offset
> +(i.e., even if the location referred to by
> +.I offset
> +is a hole,
> +it can be considered to consist of data that is a sequence of zeroes).
> +.\" https://lkml.org/lkml/2011/4/22/79
> +.\" http://lwn.net/Articles/440255/
> +.\" http://blogs.oracle.com/bonwick/entry/seek_hole_and_seek_data
>
>   .SH "RETURN VALUE"
>   Upon successful completion,
>   .BR lseek ()
> @@ -101,11 +164,14 @@ is not an open file descriptor.
>   .TP
>   .B EINVAL
>   .I whence
> -is not one of
> -.BR SEEK_SET ,
> -.BR SEEK_CUR ,
> -.BR SEEK_END ;
> -or the resulting file offset would be negative,
> +is not valid (this error may be returned if
> +.I whence
> +is
> +.BR SEEK_DATA
> +or
> +.BR SEEK_HOLE
> +and the underlying file system does not support the operation).
> +Or: the resulting file offset would be negative,
>   or beyond the end of a seekable device.
>   .\" Some systems may allow negative offsets for character devices
>   .\" and/or for remote file systems.
> @@ -118,8 +184,21 @@ The resulting file offset cannot be represented in an
>   .B ESPIPE
>   .I fd
>   is associated with a pipe, socket, or FIFO.
> +.TP
> +.B ENXIO
> +.I whence
> +is
> +.B SEEK_DATA
> +or
> +.BR SEEK_HOLE ,
> +and the current file offset is beyond the end of the file.
>   .SH "CONFORMING TO"
>   SVr4, 4.3BSD, POSIX.1-2001.
> +
> +.BR SEEK_DATA
> +and
> +.BR SEEK_HOLE
> +are nonstandard extensions also present in Solaris.
>   .SH NOTES
>   Some devices are incapable of seeking and POSIX does not specify which
>   devices must support
> --
> To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html