[Python-checkins] [3.11] gh-107801: Document SEEK_HOLE and SEEK_DATA (GH-107936) (#108087)

[erlend-aasland]

https://github.com/python/cpython/commit/1482b99061e1d7d4a49721d6290d7e48de8291c0
commit: 1482b99061e1d7d4a49721d6290d7e48de8291c0
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: erlend-aasland <erlend.aasland at protonmail.com>
date: 2023-08-17T14:22:39Z
summary:

[3.11] gh-107801: Document SEEK_HOLE and SEEK_DATA (GH-107936) (#108087)

(cherry picked from commit 8a19f225b948db1eebe1d9fc71a486258841f578)

Co-authored-by: Erlend E. Aasland <erlend at python.org>
Co-authored-by: Adam Turner <9087854+AA-Turner at users.noreply.github.com>
Co-authored-by: Antoine Pitrou <antoine at python.org>

files:
M Doc/library/os.rst

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 5577921478452..1d0d1049ebd7e 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1061,6 +1061,10 @@ as internal buffering of data.
    current position; :const:`SEEK_END` or ``2`` to set it relative to the end of
    the file. Return the new cursor position in bytes, starting from the beginning.
 
+   .. versionchanged:: 3.3
+
+      Add support for :const:`SEEK_HOLE` and :const:`SEEK_DATA`.
+
 
 .. data:: SEEK_SET
           SEEK_CUR
@@ -1069,9 +1073,30 @@ as internal buffering of data.
    Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
    respectively.
 
+
+.. data:: SEEK_HOLE
+          SEEK_DATA
+
+   Parameters to the :func:`lseek` function and the :meth:`~io.IOBase.seek`
+   method on file objects, for seeking file data and holes on sparsely
+   allocated files.
+
+   :data:`!SEEK_DATA`
+      Adjust the file offset to the next location containing data,
+      relative to the seek position.
+
+   :data:`!SEEK_HOLE`
+      Adjust the file offset to the next location containing a hole,
+      relative to the seek position.
+      A hole is defined as a sequence of zeros.
+
+   .. note::
+
+      These operations only make sense for filesystems that support them.
+
+   .. availability:: Linux >= 3.1, macOS, Unix
+
    .. versionadded:: 3.3
-      Some operating systems could support additional values, like
-      :const:`os.SEEK_HOLE` or :const:`os.SEEK_DATA`.
 
 
 .. function:: open(path, flags, mode=0o777, *, dir_fd=None)