Skip to content

os.sendfile() flags improperly ordered in documentation #107924

Closed
@calestyo

Description

@calestyo

Bug report

There are some minor issues in the documentation for which I'm about to submit MRs:

  1. There's some bad ordering around os.sendfile(), it seems to make no sense that the os.set_blocking() function comes in-between the os.sendfile() function and its flags.
  2. Also, the flags could possibly be joined into one section

cpython/Doc/library/os.rst

Lines 1542 to 1618 in cc2cf85

.. function:: sendfile(out_fd, in_fd, offset, count)
sendfile(out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)
Copy *count* bytes from file descriptor *in_fd* to file descriptor *out_fd*
starting at *offset*.
Return the number of bytes sent. When EOF is reached return ``0``.
The first function notation is supported by all platforms that define
:func:`sendfile`.
On Linux, if *offset* is given as ``None``, the bytes are read from the
current position of *in_fd* and the position of *in_fd* is updated.
The second case may be used on macOS and FreeBSD where *headers* and
*trailers* are arbitrary sequences of buffers that are written before and
after the data from *in_fd* is written. It returns the same as the first case.
On macOS and FreeBSD, a value of ``0`` for *count* specifies to send until
the end of *in_fd* is reached.
All platforms support sockets as *out_fd* file descriptor, and some platforms
allow other types (e.g. regular file, pipe) as well.
Cross-platform applications should not use *headers*, *trailers* and *flags*
arguments.
.. availability:: Unix, not Emscripten, not WASI.
.. note::
For a higher-level wrapper of :func:`sendfile`, see
:meth:`socket.socket.sendfile`.
.. versionadded:: 3.3
.. versionchanged:: 3.9
Parameters *out* and *in* was renamed to *out_fd* and *in_fd*.
.. function:: set_blocking(fd, blocking, /)
Set the blocking mode of the specified file descriptor. Set the
:data:`O_NONBLOCK` flag if blocking is ``False``, clear the flag otherwise.
See also :func:`get_blocking` and :meth:`socket.socket.setblocking`.
.. availability:: Unix, Windows.
The function is limited on Emscripten and WASI, see
:ref:`wasm-availability` for more information.
On Windows, this function is limited to pipes.
.. versionadded:: 3.5
.. versionchanged:: 3.12
Added support for pipes on Windows.
.. data:: SF_NODISKIO
SF_MNOWAIT
SF_SYNC
Parameters to the :func:`sendfile` function, if the implementation supports
them.
.. availability:: Unix, not Emscripten, not WASI.
.. versionadded:: 3.3
.. data:: SF_NOCACHE
Parameter to the :func:`sendfile` function, if the implementation supports
it. The data won't be cached in the virtual memory and will be freed afterwards.
.. availability:: Unix, not Emscripten, not WASI.
.. versionadded:: 3.11

Checklist

  • I am confident this is a bug in CPython, not a bug in a third-party project
  • I have searched the CPython issue tracker, and am confident this bug has not been reported before

Linked PRs

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dirtype-bugAn unexpected behavior, bug, or error

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions