Hi Sunil, On Mon, Sep 19, 2011 at 8:04 PM, Sunil Mushran <sunil.mushran@xxxxxxxxxx> wrote: > 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. I changed "region" to "location", but otherwise left this unchanged. I couldn't see a good alternative formulation, and also the next sentence of the page makes your point clear. >> +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. See above; no change. >> +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. Yes, better. Changed. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Author of "The Linux Programming Interface"; http://man7.org/tlpi/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
