[Python-checkins] bpo-31368: Enhance os.preadv() documentation (GH-7254)
Miss Islington (bot)
webhook-mailer at python.org
Wed May 30 19:22:16 EDT 2018
https://github.com/python/cpython/commit/0e823c6efa4729f3cd19f96af82c673b10cd3ee2
commit: 0e823c6efa4729f3cd19f96af82c673b10cd3ee2
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2018-05-30T16:22:13-07:00
summary:
bpo-31368: Enhance os.preadv() documentation (GH-7254)
(cherry picked from commit 02e2a085dc1740b1cbf4ba2ed77335c84ce8a367)
Co-authored-by: Pablo Galindo <Pablogsal at gmail.com>
files:
M Doc/library/os.rst
M Doc/whatsnew/3.7.rst
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 60ab94f4769e..d937451be51e 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1082,20 +1082,81 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. versionadded:: 3.3
-.. function:: pread(fd, buffersize, offset)
+.. function:: pread(fd, n, offset)
- Read from a file descriptor, *fd*, at a position of *offset*. It will read up
- to *buffersize* number of bytes. The file offset remains unchanged.
+ Read at most *n* bytes from file descriptor *fd* at a position of *offset*,
+ leaving the file offset unchanged.
+
+ Return a bytestring containing the bytes read. If the end of the file
+ referred to by *fd* has been reached, an empty bytes object is returned.
Availability: Unix.
.. versionadded:: 3.3
+.. function:: preadv(fd, buffers, offset, flags=0)
+
+ Read from a file descriptor *fd* at a position of *offset* into mutable
+ :term:`bytes-like objects <bytes-like object>` *buffers*, leaving the file
+ offset unchanged. 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.
+
+ The flags argument contains a bitwise OR of zero or more of the following
+ flags:
+
+ - :data:`RWF_HIPRI`
+ - :data:`RWF_NOWAIT`
+
+ Return the total number of bytes actually read which can be less than the
+ total capacity of all the objects.
+
+ The operating system may set a limit (:func:`sysconf` value
+ ``'SC_IOV_MAX'``) on the number of buffers that can be used.
+
+ Combine the functionality of :func:`os.readv` and :func:`os.pread`.
+
+ Availability: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
+ OpenBSD 2.7 and newer. Using flags requires Linux 4.6 or newer.
+
+ .. versionadded:: 3.7
+
+
+.. data:: RWF_NOWAIT
+
+ Do not wait for data which is not immediately available. If this flag is
+ specified, the 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
+ :data:`errno.EAGAIN`.
+
+ Availability: Linux 4.14 and newer.
+
+ .. versionadded:: 3.7
+
+
+.. data:: RWF_HIPRI
+
+ High priority read/write. Allows block-based filesystems to use polling
+ of the device, which provides lower latency, but may use additional
+ resources.
+
+ Currently, on Linux, this feature is usable only on a file descriptor opened
+ using the :data:`O_DIRECT` flag.
+
+ Availability: Linux 4.6 and newer.
+
+ .. versionadded:: 3.7
+
+
.. function:: pwrite(fd, str, offset)
- Write *bytestring* to a file descriptor, *fd*, from *offset*,
- leaving the file offset unchanged.
+ Write the bytestring in *str* to file descriptor *fd* at position of
+ *offset*, leaving the file offset unchanged.
+
+ Return the number of bytes actually written.
Availability: Unix.
@@ -1104,54 +1165,57 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. function:: pwritev(fd, buffers, offset, flags=0)
- Combines the functionality of :func:`os.writev` and :func:`os.pwrite`. It
- writes the contents of *buffers* to file descriptor *fd* at offset *offset*.
- *buffers* must be a sequence of :term:`bytes-like objects <bytes-like object>`.
- 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.
- :func:`~os.pwritev` writes the contents of each object to the file descriptor
- and returns the total number of bytes written.
+ Write the *buffers* contents to file descriptor *fd* at a offset *offset*,
+ leaving the file offset unchanged. *buffers* must be a sequence of
+ :term:`bytes-like objects <bytes-like object>`. Buffers are processed in
+ array order. Entire contents of the first buffer is written before
+ proceeding to the second, and so on.
- The *flags* argument contains a bitwise OR of zero or more of the following
+ The flags argument contains a bitwise OR of zero or more of the following
flags:
- - RWF_DSYNC
- - RWF_SYNC
+ - :data:`RWF_DSYNC`
+ - :data:`RWF_SYNC`
- Using non-zero flags requires Linux 4.7 or newer.
+ Return the total number of bytes actually written.
- Availability: Linux (version 2.6.30), FreeBSD 6.0 and newer,
- OpenBSD (version 2.7 and newer).
+ The operating system may set a limit (:func:`sysconf` value
+ ``'SC_IOV_MAX'``) on the number of buffers that can be used.
+
+ Combine the functionality of :func:`os.writev` and :func:`os.pwrite`.
+
+ Availability: Linux 2.6.30 and newer, FreeBSD 6.0 and newer,
+ OpenBSD 2.7 and newer. Using flags requires Linux 4.7 or newer.
.. versionadded:: 3.7
+
.. data:: RWF_DSYNC
- 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.
+ Provide a per-write equivalent of the :data:`O_DSYNC` ``open(2)`` flag. This
+ flag effect applies only to the data range written by the system call.
- Availability: Linux (version 4.7).
+ Availability: Linux 4.7 and newer.
.. versionadded:: 3.7
+
.. data:: RWF_SYNC
- 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.
+ Provide a per-write equivalent of the :data:`O_SYNC` ``open(2)`` flag. This
+ flag effect applies only to the data range written by the system call.
- Availability: Linux (version 4.7).
+ Availability: Linux 4.7 and newer.
.. versionadded:: 3.7
.. function:: read(fd, n)
- Read at most *n* bytes from file descriptor *fd*. Return a bytestring containing the
- bytes read. If the end of the file referred to by *fd* has been reached, an
- empty bytes object is returned.
+ Read at most *n* bytes from file descriptor *fd*.
+
+ Return a bytestring containing the bytes read. If the end of the file
+ referred to by *fd* has been reached, an empty bytes object is returned.
.. note::
@@ -1230,66 +1294,19 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. function:: readv(fd, buffers)
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).
+ objects <bytes-like object>` *buffers*. 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.
- Availability: Unix.
-
- .. versionadded:: 3.3
+ Return the total number of bytes actually read which can be less than the
+ total capacity of all the objects.
+ The operating system may set a limit (:func:`sysconf` value
+ ``'SC_IOV_MAX'``) on the number of buffers that can be used.
-.. function:: preadv(fd, buffers, offset, flags=0)
-
- Combines the functionality of :func:`os.readv` and :func:`os.pread`. It
- reads from a file descriptor *fd* into a number of mutable :term:`bytes-like
- objects <bytes-like object>` *buffers*. As :func:`os.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, *offset*,
- specifies the file offset at which the input operation is to be performed.
- :func:`~os.preadv` 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.
-
- Availability: Linux (version 2.6.30), FreeBSD 6.0 and newer,
- OpenBSD (version 2.7 and newer).
-
- .. versionadded:: 3.7
-
-
-.. data:: RWF_HIPRI
-
- 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.)
-
- Availability: Linux (version 4.6).
-
- .. versionadded:: 3.7
-
-
-.. data:: RWF_NOWAIT
-
- 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().
-
- Availability: Linux (version 4.14).
+ Availability: Unix.
- .. versionadded:: 3.7
+ .. versionadded:: 3.3
.. function:: tcgetpgrp(fd)
@@ -1319,8 +1336,9 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. function:: write(fd, str)
- Write the bytestring in *str* to file descriptor *fd*. Return the number of
- bytes actually written.
+ Write the bytestring in *str* to file descriptor *fd*.
+
+ Return the number of bytes actually written.
.. note::
@@ -1338,14 +1356,15 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. function:: writev(fd, buffers)
- Write the contents of *buffers* to file descriptor *fd*. *buffers* must be a
- sequence of :term:`bytes-like objects <bytes-like object>`. 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.
+ Write the contents of *buffers* to file descriptor *fd*. *buffers* must be
+ a sequence of :term:`bytes-like objects <bytes-like object>`. Buffers are
+ processed in array order. Entire contents of the first buffer is written
+ before proceeding to the second, and so on.
+
+ Returns the total number of bytes actually written.
- :func:`~os.writev` writes the contents of each object to the file descriptor
- and returns the total number of bytes written.
+ The operating system may set a limit (:func:`sysconf` value
+ ``'SC_IOV_MAX'``) on the number of buffers that can be used.
Availability: Unix.
diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst
index 2471989ec7b9..9989eaf5eac5 100644
--- a/Doc/whatsnew/3.7.rst
+++ b/Doc/whatsnew/3.7.rst
@@ -1091,9 +1091,10 @@ The new :func:`~os.register_at_fork` function allows registering Python
callbacks to be executed at process fork.
(Contributed by Antoine Pitrou in :issue:`16500`.)
-Exposed the *preadv*, *preadv2*, *pwritev* and *pwritev2* system calls through
-the new :func:`~os.preadv` and :func:`~os.pwritev` functions.
-(Contributed by Pablo Galindo in :issue:`31368`.)
+Added :func:`os.preadv` (combine the functionality of :func:`os.readv` and
+:func:`os.pread`) and :func:`os.pwritev` functions (combine the functionality
+of :func:`os.writev` and :func:`os.pwrite`). (Contributed by Pablo Galindo in
+:issue:`31368`.)
The mode argument of :func:`os.makedirs` no longer affects the file
permission bits of newly-created intermediate-level directories.
More information about the Python-checkins
mailing list