summaryrefslogtreecommitdiff
path: root/doc/ref/api-io.texi
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2024-04-15 19:48:10 +0200
committerLudovic Courtès <ludo@gnu.org>2024-04-15 19:58:25 +0200
commit696acfc9e590ecff70ff369460304e96b269efe5 (patch)
tree8681a47921281310b9d34f4c0214412c49a4d922 /doc/ref/api-io.texi
parent4a0c2433d97be9d995b3be74d90bc074d8efb5a7 (diff)
downloadguile-696acfc9e590ecff70ff369460304e96b269efe5.tar.gz
‘seek’ now accepts ‘SEEK_DATA’ and ‘SEEK_HOLE’ where supported.
* libguile/ports.c (scm_seek): Let SEEK_DATA and SEEK_HOLE through. (scm_init_ice_9_ports): Define ‘SEEK_DATA’ and ‘SEEK_HOLE’. * module/ice-9/ports.scm: Export ‘SEEK_DATA’ and ‘SEEK_HOLE’ when defined. * test-suite/tests/ports.test ("size of sparse file") ("SEEK_DATA while on data", "SEEK_DATA while in hole") ("SEEK_HOLE while in hole"): New tests. * NEWS: Update.
Diffstat (limited to 'doc/ref/api-io.texi')
-rw-r--r--doc/ref/api-io.texi22
1 files changed, 20 insertions, 2 deletions
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index e263e2985..3dd2b6fa0 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -823,8 +823,26 @@ Seek from the current position.
@defvar SEEK_END
Seek from the end of the file.
@end defvar
-If @var{fd_port} is a file descriptor, the underlying system
-call is @code{lseek}. @var{port} may be a string port.
+
+On systems that support it, such as GNU/Linux, the following
+constants can be used for @var{whence} to navigate ``holes'' in
+sparse files:
+@defvar SEEK_DATA
+Seek to the next location in the file greater than or equal to
+@var{offset} containing data. If @var{offset} points to data,
+then the file offset is set to @var{offset}.
+@end defvar
+@defvar SEEK_HOLE
+Seek to the next hole in the file greater than or equal to the
+@var{offset}. If @var{offset} points into the middle of a hole,
+then the file offset is set to @var{offset}. If there is no hole
+past @var{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.
+@end defvar
+
+If @var{fd_port} is a file descriptor, the underlying system call
+is @code{lseek} (@pxref{File Position Primitive,,, libc, The GNU C
+Library Reference Manual}). @var{port} may be a string port.
The value returned is the new position in @var{fd_port}. This means
that the current position of a port can be obtained using: