Skip to content

bpo-31368: Enhance os.preadv() documentation #5415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
vstinner wants to merge 5 commits into from
+124 −88
Closed

bpo-31368: Enhance os.preadv() documentation #5415

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
52b4da1
bpo-31368: Enhance os.preadv() documentation
vstinner Jan 29, 2018
5809a57
What's New: describe added functions
vstinner Jan 29, 2018
14eafd2
Adding missing "the" in the doc
vstinner Jan 29, 2018
622a8ec
Move preadv to fix ordering
vstinner Jan 29, 2018
40457cb
Cleanup other read/write docs
vstinner Jan 29, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
207 changes: 119 additions & 88 deletions Doc/library/os.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

@vadmium vadmium Jan 30, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs a comma: “. . . number of bytes read, which can be less . . .”. Applies to readv below too.


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`.

@vadmium vadmium Jan 30, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This reads as an instruction, but it is no longer clear it is for the implementation. Maybe drop the imperative and write “This function combines the functionality . . .”. Also applies to pwritev below.


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`.

@vadmium vadmium Jan 30, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’m confused. Normally you access errno as an attribute of an exception. Do the Python wrapper(s) return −1 or raise OSError/BlockingIOError?


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 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.

Expand All @@ -1104,48 +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*,

@vadmium vadmium Jan 30, 2018

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a → an or the, or even better “at offset offset” would work I think.

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
flags:

- RWF_DSYNC
- RWF_SYNC
- :data:`RWF_DSYNC`
- :data:`RWF_SYNC`

Return the total number of bytes actually written.

Using non-zero flags requires Linux 4.7 or newer.
The operating system may set a limit (:func:`sysconf` value
``'SC_IOV_MAX'``) on the number of buffers that can be used.

Availability: Linux (version 2.6.30), FreeBSD 6.0 and newer,
OpenBSD (version 2.7 and newer).
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 (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

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 4.7 and newer.

.. versionadded:: 3.7

.. 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.

.. data:: RWF_SYNC

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 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::

Expand Down Expand Up @@ -1224,60 +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).

Availability: Unix.

.. 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
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.

Using non-zero flags requires Linux 4.6 or newer.
Return the total number of bytes actually read which can be less than the
total capacity of all the objects.

Availability: Linux (version 2.6.30), FreeBSD 6.0 and newer,
OpenBSD (version 2.7 and newer).

.. versionadded:: 3.7


.. 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.)
The operating system may set a limit (:func:`sysconf` value
``'SC_IOV_MAX'``) on the number of buffers that can be used.

.. versionadded:: 3.7


.. 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().
Availability: Unix.

.. versionadded:: 3.7
.. versionadded:: 3.3


.. function:: tcgetpgrp(fd)
Expand Down Expand Up @@ -1307,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::

Expand All @@ -1326,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.

Expand Down
5 changes: 5 additions & 0 deletions Doc/whatsnew/3.7.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -554,6 +554,11 @@ operation. (Contributed by Mark Dickinson in :issue:`29962`.)
os
--

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`.)

Added support for :class:`bytes` paths in :func:`~os.fwalk`. (Contributed by
Serhiy Storchaka in :issue:`28682`.)

Expand Down