mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-30 12:21:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

bpo-31368: Enhance os.preadv() documentation (GH-7254)

Browse source 
(cherry picked from commit 02e2a085dc)

Co-authored-by: Pablo Galindo <Pablogsal@gmail.com>
This commit is contained in:
Miss Islington (bot) 2018-05-30 16:22:13 -07:00 • committed by GitHub
parent 5191892c29
commit 0e823c6efa
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 118 additions and 98 deletions
Download patch file Download diff file Expand all files Collapse all files

209
Doc/library/os.rst
View file

@ -1082,20 +1082,81 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. versionadded:: 3.3 .. 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 Read at most *n* bytes from file descriptor *fd* at a position of *offset*,
to *buffersize* number of bytes. The file offset remains unchanged. 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. Availability: Unix.
.. versionadded:: 3.3 .. 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) .. function:: pwrite(fd, str, offset)
Write *bytestring* to a file descriptor, *fd*, from *offset*, Write the bytestring in *str* to file descriptor *fd* at position of
leaving the file offset unchanged. *offset*, leaving the file offset unchanged.
Return the number of bytes actually written.
Availability: Unix. 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) .. function:: pwritev(fd, buffers, offset, flags=0)
Combines the functionality of :func:`os.writev` and :func:`os.pwrite`. It Write the *buffers* contents to file descriptor *fd* at a offset *offset*,
writes the contents of *buffers* to file descriptor *fd* at offset *offset*. leaving the file offset unchanged. *buffers* must be a sequence of
*buffers* must be a sequence of :term:`bytes-like objects <bytes-like object>`. :term:`bytes-like objects <bytes-like object>`. Buffers are processed in
Buffers are processed in array order. Entire contents of first buffer is written array order. Entire contents of the first buffer is written before
before proceeding to second, and so on. The operating system may set a limit proceeding to the second, and so on.
(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.
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: flags:
- RWF_DSYNC - :data:`RWF_DSYNC`
- RWF_SYNC - :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, The operating system may set a limit (:func:`sysconf` value
OpenBSD (version 2.7 and newer). ``'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 .. versionadded:: 3.7
.. data:: RWF_DSYNC .. data:: RWF_DSYNC
Provide a per-write equivalent of the O_DSYNC open(2) flag. This flag Provide a per-write equivalent of the :data:`O_DSYNC` ``open(2)`` flag. This
is meaningful only for pwritev2(), and its effect applies only to the flag effect applies only to the data range written by the system call.
data range written by the system call.
Availability: Linux (version 4.7). Availability: Linux 4.7 and newer.
.. versionadded:: 3.7 .. versionadded:: 3.7
.. data:: RWF_SYNC .. data:: RWF_SYNC
Provide a per-write equivalent of the O_SYNC open(2) flag. This flag is Provide a per-write equivalent of the :data:`O_SYNC` ``open(2)`` flag. This
meaningful only for pwritev2(), and its effect applies only to the data flag effect applies only to the data range written by the system call.
range written by the system call.
Availability: Linux (version 4.7). Availability: Linux 4.7 and newer.
.. versionadded:: 3.7 .. versionadded:: 3.7
.. function:: read(fd, n) .. function:: read(fd, n)
Read at most *n* bytes from file descriptor *fd*. Return a bytestring containing the Read at most *n* bytes from file descriptor *fd*.
bytes read. If the end of the file referred to by *fd* has been reached, an
empty bytes object is returned. 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:: .. note::
@ -1230,68 +1294,21 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. function:: readv(fd, buffers) .. function:: readv(fd, buffers)
Read from a file descriptor *fd* into a number of mutable :term:`bytes-like 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 objects <bytes-like object>` *buffers*. Transfer data into each buffer until
into each buffer until it is full and then move on to the next buffer in the it is full and then move on to the next buffer in the sequence to hold the
sequence to hold the rest of the data. :func:`~os.readv` returns the total rest of the data.
number of bytes read (which may be less than the total capacity of all the
objects). 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.
Availability: Unix. Availability: Unix.
.. versionadded:: 3.3 .. versionadded:: 3.3
.. 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).
.. versionadded:: 3.7
.. function:: tcgetpgrp(fd) .. function:: tcgetpgrp(fd)
Return the process group associated with the terminal given by *fd* (an open Return the process group associated with the terminal given by *fd* (an open
@ -1319,8 +1336,9 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. function:: write(fd, str) .. function:: write(fd, str)
Write the bytestring in *str* to file descriptor *fd*. Return the number of Write the bytestring in *str* to file descriptor *fd*.
bytes actually written.
Return the number of bytes actually written.
.. note:: .. note::
@ -1338,14 +1356,15 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo
.. function:: writev(fd, buffers) .. function:: writev(fd, buffers)
Write the contents of *buffers* to file descriptor *fd*. *buffers* must be a Write the contents of *buffers* to file descriptor *fd*. *buffers* must be
sequence of :term:`bytes-like objects <bytes-like object>`. Buffers are a sequence of :term:`bytes-like objects <bytes-like object>`. Buffers are
processed in array order. Entire contents of first buffer is written before processed in array order. Entire contents of the first buffer is written
proceeding to second, and so on. The operating system may set a limit before proceeding to the second, and so on.
(sysconf() value SC_IOV_MAX) on the number of buffers that can be used.
:func:`~os.writev` writes the contents of each object to the file descriptor Returns the total number of bytes actually written.
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. Availability: Unix.

7
Doc/whatsnew/3.7.rst
View file

@ -1091,9 +1091,10 @@ The new :func:`~os.register_at_fork` function allows registering Python
callbacks to be executed at process fork. callbacks to be executed at process fork.
(Contributed by Antoine Pitrou in :issue:`16500`.) (Contributed by Antoine Pitrou in :issue:`16500`.)
Exposed the *preadv*, *preadv2*, *pwritev* and *pwritev2* system calls through Added :func:`os.preadv` (combine the functionality of :func:`os.readv` and
the new :func:`~os.preadv` and :func:`~os.pwritev` functions. :func:`os.pread`) and :func:`os.pwritev` functions (combine the functionality
(Contributed by Pablo Galindo in :issue:`31368`.) 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 The mode argument of :func:`os.makedirs` no longer affects the file
permission bits of newly-created intermediate-level directories. permission bits of newly-created intermediate-level directories.