Correct typos, docstring and improve Docs

Author: pablogsal

Doc/library/os.rst

@@ -1112,34 +1112,30 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    :func:`~os.pwritev` writes the contents of each object to the file descriptor
    and returns the total number of bytes written.
 
-
    The *flags* argument contains a bitwise OR of zero or more of the following
    flags:
 
    - RWF_DSYNC
    - RWF_SYNC
 
-   :func:`~os.pwritev` will call *pwritev2* system call if available, which modifies
-   the behavior on a per-call basis based on the value of the *flags* argument. The
-   :func:`~os.pwritev2` function is required to pass flags.
-
-   The :func:`~os.pwritev2` function is required to pass flags.
-
-   *pwritev2* and *flags* different than zero are available since Linux version
-   4.7.
+   Using non-zero flags requires Linux 4.7 or newer.
 
    Availability: Linux (version 2.6.30), FreeBSD 6.0 and newer,
    OpenBSD (version 2.7 and newer).
 
    .. versionadded:: 3.7
 
+.. data:: RWF_DSYNC (since Linux 4.7)
+   Provide a per-write equivalent of the O_DSYNC open(2) flag. This flag
+   is meaningful only for pwritev2(), and its effect applies only to the
+   data range written by the system call.
 
-.. data:: RWF_DSYNC
-          RWF_SYNC
-
-   The above constants are available on Linux Kernel 4.7 (or newer).
+   .. versionadded:: 3.7
 
-   Availability: Linux.
+.. data:: RWF_SYNC (since Linux 4.7)
+   Provide a per-write equivalent of the O_SYNC open(2) flag. This flag is
+   meaningful only for pwritev2(), and its effect applies only to the data
+   range written by the system call.
 
    .. versionadded:: 3.7
 
@@ -1252,29 +1248,33 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
    The flags argument contains a bitwise OR of zero or more of the following
    flags:
 
-       - RWF_HIPRI
-       - RWF_NOWAIT
+   - RWF_HIPRI
+   - RWF_NOWAIT
 
-   :func:`~os.preadv` will call *preadv2* system call if available, which modifies
-   the behavior on a per-call basis based on the value of the *flags* argument. The
-   :c:func:`preadv2` function is required to pass flags.
-
-   *preadv2* and flags different than zero are available since Linux version
-   4.6 and newer.
+   Using non-zero flags requires Linux 4.6 or newer.
 
    Availability: Linux (version 2.6.30), FreeBSD 6.0 and newer,
    OpenBSD (version 2.7 and newer).
 
    .. versionadded:: 3.7
 
 
-.. data:: RWF_HIPRI
-          RWF_NOWAIT
+.. data:: RWF_HIPRI (since Linux 4.6)
+   High priority read/write. Allows block-based filesystems to use polling
+   of the device, which provides lower latency, but may use additional
+   resources. (Currently, this feature is usable only on a file descriptor
+   opened using the O_DIRECT flag.)
+
+   .. versionadded:: 3.7
 
-   The above constants are available on Linux Kernel 4.11 and 4.6 (or newer)
-   respectively.
 
-   Availability: Linux.
+.. data:: RWF_NOWAIT (since Linux 4.14)
+   Do not wait for data which is not immediately available. If this flag
+   is  specified, the preadv2() system call will return instantly
+   if it would have to read data from the backing storage or wait for a lock.
+   If some data was successfully read, it will return the number of bytes
+   read. If no bytes were read, it will return -1 and set errno to EAGAIN.
+   Currently, this flag is meaningful only for preadv2().
 
    .. versionadded:: 3.7
 

Lib/test/test_posix.py

@@ -309,18 +309,16 @@ def test_pwrite(self):
     def test_pwritev(self):
         fd = os.open(support.TESTFN, os.O_RDWR | os.O_CREAT)
         try:
-            os.write(fd,b"xx")
+            os.write(fd, b"xx")
             os.lseek(fd, 0, os.SEEK_SET)
             n = os.pwritev(fd, [b'test1', b'tt2', b't3'], 2)
             self.assertEqual(n, 10)
 
             os.lseek(fd, 0, os.SEEK_SET)
-            self.assertEqual(b'xxtest1tt2', posix.read(fd, 10))
-
+            self.assertEqual(b'xxtest1tt2t3', posix.read(fd, 100))
         finally:
             os.close(fd)
 
-
     @unittest.skipUnless(hasattr(posix, 'os.RWF_SYNC'), "test needs os.RWF_SYNC")
     def test_pwritev_flags(self):
         fd = os.open(support.TESTFN, os.O_RDWR | os.O_CREAT)
@@ -331,11 +329,10 @@ def test_pwritev_flags(self):
             self.assertEqual(n, 10)
 
             os.lseek(fd, 0, os.SEEK_SET)
-            self.assertEqual(b'xxtest1tt2', posix.read(fd, 10))
+            self.assertEqual(b'xxtest1tt2', posix.read(fd, 100))
         finally:
             os.close(fd)
 
-
     @unittest.skipUnless(hasattr(posix, 'posix_fallocate'),
         "test needs posix.posix_fallocate()")
     def test_posix_fallocate(self):

Misc/NEWS.d/next/Core and Builtins/2018-01-19-01-54-22.bpo-31368.kzKqUR.rst

@@ -1,2 +1 @@
-Expose preadv (preadv2) and pwritev (pwritev2) system calls in the os module.
-Patch by Pablo Galindo
+Expose preadv and pwritev system calls in the os module. Patch by Pablo Galindo

Modules/clinic/posixmodule.c.h

@@ -3711,10 +3711,21 @@ PyDoc_STRVAR(os_preadv__doc__,
 "preadv($module, fd, buffers, offset, flags=0, /)\n"
 "--\n"
 "\n"
-"Read a number of bytes from a file descriptor starting at a particular offset.\n"
+"Reads from a file descriptor into a number of mutable bytes-like objects.\n"
 "\n"
-"Read length bytes from file descriptor fd, starting at offset bytes from\n"
-"the beginning of the file.  The file offset remains unchanged.");
+"Combines the functionality of readv() and pread(). As readv(), it will\n"
+"transfer data into each buffer until it is full and then move on to the next\n"
+"buffer in the sequence to hold the rest of the data. Its fourth argument,\n"
+"specifies the file offset at which the input operation is to be performed. It\n"
+"will return the total number of bytes read (which can be less than the total\n"
+"capacity of all the objects).\n"
+"\n"
+"The flags argument contains a bitwise OR of zero or more of the following flags:\n"
+"\n"
+"- RWF_HIPRI\n"
+"- RWF_NOWAIT\n"
+"\n"
+"Using non-zero flags requires Linux 4.6 or newer.");
 
 #define OS_PREADV_METHODDEF    \
     {"preadv", (PyCFunction)os_preadv, METH_FASTCALL, os_preadv__doc__},
@@ -4013,11 +4024,21 @@ PyDoc_STRVAR(os_pwritev__doc__,
 "pwritev($module, fd, buffers, offset, flags=0, /)\n"
 "--\n"
 "\n"
-"Write bytes to a file descriptor starting at a particular offset.\n"
+"Writes the contents of bytes-like objects to a file descriptor at a given offset.\n"
 "\n"
-"Write buffer to fd, starting at offset bytes from the beginning of\n"
-"the file.  Returns the number of bytes writte.  Does not change the\n"
-"current file offset.");
+"Combines the functionality of writev() and pwrite(). All buffers must be a sequence\n"
+"of bytes-like objects. Buffers are processed in array order. Entire contents of first\n"
+"buffer is written before proceeding to second, and so on. The operating system may\n"
+"set a limit (sysconf() value SC_IOV_MAX) on the number of buffers that can be used.\n"
+"This function writes the contents of each object to the file descriptor and returns\n"
+"the total number of bytes written.\n"
+"\n"
+"The flags argument contains a bitwise OR of zero or more of the following flags:\n"
+"\n"
+"- RWF_DSYNC\n"
+"- RWF_SYNC\n"
+"\n"
+"Using non-zero flags requires Linux 4.7 or newer.");
 
 #define OS_PWRITEV_METHODDEF    \
     {"pwritev", (PyCFunction)os_pwritev, METH_FASTCALL, os_pwritev__doc__},
@@ -6507,4 +6528,4 @@ os_getrandom(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject
 #ifndef OS_GETRANDOM_METHODDEF
     #define OS_GETRANDOM_METHODDEF
 #endif /* !defined(OS_GETRANDOM_METHODDEF) */
-/*[clinic end generated code: output=d50830cf566cb297 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=06ace805893aa10c input=a9049054013a1b77]*/

Modules/posixmodule.c

@@ -8173,16 +8173,27 @@ os.preadv -> Py_ssize_t
     flags: int = 0
     /
 
-Read a number of bytes from a file descriptor starting at a particular offset.
+Reads from a file descriptor into a number of mutable bytes-like objects.
 
-Read length bytes from file descriptor fd, starting at offset bytes from
-the beginning of the file.  The file offset remains unchanged.
+Combines the functionality of readv() and pread(). As readv(), it 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. Its fourth argument,
+specifies the file offset at which the input operation is to be performed. It
+will return the total number of bytes read (which can be less than the total
+capacity of all the objects).
+
+The flags argument contains a bitwise OR of zero or more of the following flags:
+
+- RWF_HIPRI
+- RWF_NOWAIT
+
+Using non-zero flags requires Linux 4.6 or newer.
 [clinic start generated code]*/
 
 static Py_ssize_t
 os_preadv_impl(PyObject *module, int fd, PyObject *buffers, Py_off_t offset,
                int flags)
-/*[clinic end generated code: output=26fc9c6e58e7ada5 input=5b07b7e2d1825627]*/
+/*[clinic end generated code: output=26fc9c6e58e7ada5 input=4173919dc1f7ed99]*/
 {
     Py_ssize_t cnt, n;
     int async_err = 0;
@@ -8700,17 +8711,27 @@ os.pwritev -> Py_ssize_t
     flags: int = 0
     /
 
-Write bytes to a file descriptor starting at a particular offset.
+Writes the contents of bytes-like objects to a file descriptor at a given offset.
 
-Write buffer to fd, starting at offset bytes from the beginning of
-the file.  Returns the number of bytes writte.  Does not change the
-current file offset.
+Combines the functionality of writev() and pwrite(). All buffers must be a sequence
+of bytes-like objects. Buffers are processed in array order. Entire contents of first
+buffer is written before proceeding to second, and so on. The operating system may
+set a limit (sysconf() value SC_IOV_MAX) on the number of buffers that can be used.
+This function writes the contents of each object to the file descriptor and returns
+the total number of bytes written.
+
+The flags argument contains a bitwise OR of zero or more of the following flags:
+
+- RWF_DSYNC
+- RWF_SYNC
+
+Using non-zero flags requires Linux 4.7 or newer.
 [clinic start generated code]*/
 
 static Py_ssize_t
 os_pwritev_impl(PyObject *module, int fd, PyObject *buffers, Py_off_t offset,
                 int flags)
-/*[clinic end generated code: output=e3dd3e9d11a6a5c7 input=76ec1699089ae61c]*/
+/*[clinic end generated code: output=e3dd3e9d11a6a5c7 input=803dc5ddbf0cfd3b]*/
 {
     Py_ssize_t cnt;
     Py_ssize_t result;