improve description of buffers argument for readv/writev (closes #17811)

Patch by Nikolaus Rath.

1 files changed, 12 insertions, 8 deletions

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 20f3e87..b11098e 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1019,10 +1019,13 @@ as internal buffering of data.
 
 .. function:: readv(fd, buffers)
 
-   Read from a file descriptor into a number of writable buffers. *buffers* is
-   an arbitrary sequence of writable buffers. Returns the total number of bytes
-   read.
-
+   Read from a file descriptor *fd* into a number of mutable :term:`bytes-like
+   objects <bytes-like object>` *buffers*. :func:`~os.readv` will transfer data
+   into each buffer until it is full and then move on to the next buffer in the
+   sequence to hold the rest of the data. :func:`~os.readv` returns the total
+   number of bytes read (which may be less than the total capacity of all the
+   objects).
+          
    Availability: Unix.
 
    .. versionadded:: 3.3
@@ -1071,10 +1074,11 @@ as internal buffering of data.
 
 .. function:: writev(fd, buffers)
 
-   Write the contents of *buffers* to file descriptor *fd*, where *buffers*
-   is an arbitrary sequence of buffers.
-   Returns the total number of bytes written.
-
+   Write the contents of *buffers* to file descriptor *fd*. *buffers* must be a
+   sequence of :term:`bytes-like objects <bytes-like object>`.
+   :func:`~os.writev` writes the contents of each object to the file descriptor
+   and returns the total number of bytes written.
+   
    Availability: Unix.
 
    .. versionadded:: 3.3