diff options
author | pjd <pjd@FreeBSD.org> | 2007-04-05 21:10:53 +0000 |
---|---|---|
committer | pjd <pjd@FreeBSD.org> | 2007-04-05 21:10:53 +0000 |
commit | 4718e01f98485788a9f7b2defc77a984780db526 (patch) | |
tree | c358a7e9b774044c343bcf2b36dc569901065d03 /lib | |
parent | 7e73da14eb8410d6878c1e60cdb665d8a8c74c47 (diff) | |
download | FreeBSD-src-4718e01f98485788a9f7b2defc77a984780db526.zip FreeBSD-src-4718e01f98485788a9f7b2defc77a984780db526.tar.gz |
Implement SEEK_DATA and SEEK_HOLE extensions to lseek(2) as found in
OpenSolaris. For more information please refer to:
http://blogs.sun.com/bonwick/entry/seek_hole_and_seek_data
Diffstat (limited to 'lib')
-rw-r--r-- | lib/libc/sys/lseek.2 | 54 | ||||
-rw-r--r-- | lib/libc/sys/pathconf.2 | 12 |
2 files changed, 65 insertions, 1 deletions
diff --git a/lib/libc/sys/lseek.2 b/lib/libc/sys/lseek.2 index df225f3..6fdf79b 100644 --- a/lib/libc/sys/lseek.2 +++ b/lib/libc/sys/lseek.2 @@ -87,6 +87,23 @@ the offset is set to the size of the file plus .Fa offset bytes. +.It +If +.Fa whence +is +.Dv SEEK_HOLE , +the offset of the start of the next hole greater than or equal to the supplied +.Fa offset +is returned. +The definition of a hole is provided below. +.It +If +.Fa whence +is +.Dv SEEK_DATA , +the offset is set to the start of the next non-hole file region greater +than or equal to the supplied +.Fa offset . .El .Pp The @@ -100,6 +117,33 @@ bytes of zeros (until data is actually written into the gap). Some devices are incapable of seeking. The value of the pointer associated with such a device is undefined. +.Pp +A +.Qq hole +is defined as a contiguous range of bytes in a file, all having the value of +zero, but not all zeros in a file are guaranteed to be represented as holes +returned with +.Dv SEEK_HOLE . +File systems are allowed to expose ranges of zeros with +.Dv SEEK_HOLE , +but not required to. +Applications can use +.Dv SEEK_HOLE +to optimise their behavior for ranges of zeros, but must not depend on it to +find all such ranges in a file. +The existence of a hole at the end of every data region allows for easy +programming and implies that a virtual hole exists at the end of the file. +Applications should use +.Fn fpathconf _PC_MIN_HOLE_SIZE +or +.Fn pathconf _PC_MIN_HOLE_SIZE +to determine if a file system supports +.Dv SEEK_HOLE . +See +.Xr pathconf 2 . +.Pp +For file systems that do not supply information about holes, the file will be +represented as one entire data region. .Sh RETURN VALUES Upon successful completion, .Fn lseek @@ -128,6 +172,13 @@ argument is not a proper value or the resulting file offset would be negative for a non-character special file. +.It Bq Er ENXIO +For +.Dv SEEK_DATA , +there are no more data regions past the supplied offset. +For +.Dv SEEK_HOLE , +there are no more holes past the supplied offset. .It Bq Er EOVERFLOW The resulting file offset would be a value which cannot be represented correctly in an object of type @@ -140,7 +191,8 @@ is associated with a pipe, socket, or FIFO. .El .Sh SEE ALSO .Xr dup 2 , -.Xr open 2 +.Xr open 2 , +.Xr pathconf 2 .Sh STANDARDS The .Fn lseek diff --git a/lib/libc/sys/pathconf.2 b/lib/libc/sys/pathconf.2 index e3c17d6..968f307 100644 --- a/lib/libc/sys/pathconf.2 +++ b/lib/libc/sys/pathconf.2 @@ -144,6 +144,17 @@ otherwise 0. .It Li _PC_MAC_PRESENT Returns 1 if a Mandatory Access Control (MAC) label can be set on the specified file, otherwise 0. +.It Li _PC_MIN_HOLE_SIZE +If a file system supports the reporting of holes (see +.Xr lseek 2 , +.Fn pathconf +and +.Fn fpathconf +return a positive number that represents the minimum hole size returned in +bytes. +The offsets of holes returned will be aligned to this same value. +A special value of 1 is returned if the file system does not specify the minimum +hole size but still reports holes. .El .Sh RETURN VALUES If the call to @@ -216,6 +227,7 @@ is not a valid open file descriptor. An I/O error occurred while reading from or writing to the file system. .El .Sh SEE ALSO +.Xr lseek 2 , .Xr sysctl 3 .Sh HISTORY The |