Docs: Add `os.splice` flags argument (#109847)

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Blaise Pabon <blaise@gmail.com>

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 8d95d01fe55ed93f09f30556fca7e6500bf35058..2878d425310d755178d467a927bf1f8755da8505 100644 (file)
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1724,10 +1724,27 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
       Added support for pipes on Windows.
 
 
-.. function:: splice(src, dst, count, offset_src=None, offset_dst=None)
+.. function:: splice(src, dst, count, offset_src=None, offset_dst=None, flags=0)
 
    Transfer *count* bytes from file descriptor *src*, starting from offset
    *offset_src*, to file descriptor *dst*, starting from offset *offset_dst*.
+
+   The splicing behaviour can be modified by specifying a *flags* value.
+   Any of the following variables may used, combined using bitwise OR
+   (the ``|`` operator):
+
+   * If :const:`SPLICE_F_MOVE` is specified,
+     the kernel is asked to move pages instead of copying,
+     but pages may still be copied if the kernel cannot move the pages from the pipe.
+
+   * If :const:`SPLICE_F_NONBLOCK` is specified,
+     the kernel is asked to not block on I/O.
+     This makes the splice pipe operations nonblocking,
+     but splice may nevertheless block because the spliced file descriptors may block.
+
+   * If :const:`SPLICE_F_MORE` is specified,
+     it hints to the kernel that more data will be coming in a subsequent splice.
+
    At least one of the file descriptors must refer to a pipe. If *offset_src*
    is ``None``, then *src* is read from the current position; respectively for
    *offset_dst*. The offset associated to the file descriptor that refers to a
@@ -1746,6 +1763,8 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    make sense to block because there are no writers connected to the write end
    of the pipe.
 
+   .. seealso:: The :manpage:`splice(2)` man page.
+
    .. availability:: Linux >= 2.6.17 with glibc >= 2.5
 
    .. versionadded:: 3.10