gh-132742: Update documentation for the fcntl module #132765
Conversation
serhiy-storchaka
added
docs
|
I’m not an expert on fcntl, did you just want a style/editorial review from me here? A |
|
I would be grateful for a style/editorial review. I feel like there is some incorrect or unclear English here. |
| the *mutate_flag* parameter. | ||
|
|
||
| If it is false, the buffer's mutability is ignored and behaviour is as for a | ||
| read-only buffer, except that the 1024 byte limit mentioned above is avoided -- |
There was a problem hiding this comment.
This was incorrect, the 1024 byte limit is not avoided if mutate_flag is false.
Doc/library/fcntl.rst
Outdated
| supplied buffer is less than 1024 bytes long it is first copied into a static | ||
| buffer 1024 bytes long which is then passed to :func:`ioctl` and copied back | ||
| into the supplied buffer. | ||
|
|
||
| If the :c:func:`ioctl` call fails, an :exc:`OSError` exception is raised. | ||
|
|
||
| .. note:: | ||
| If the type or the size of *arg* does not match the type or the size |
There was a problem hiding this comment.
In the C documentation, the type is int or a pointer to specific structure. The Python argument must be int or a bytes-like object of the corresponding size.
| :func:`struct.pack`. The binary data is copied to a buffer whose address is | ||
| :class:`bytes` object, or a string. | ||
| The type and the size of *arg* must match the type and the size of | ||
| the argument of the operation as specified in the relevant C documentation. |
There was a problem hiding this comment.
Depending on platform. Various manpages on Posix systems, some Microsoft links on Windows.
| The parameter *arg* can be one of an integer, a :term:`bytes-like object`, | ||
| or a string. | ||
| The type and the size of *arg* must match the type and the size of | ||
| the argument of the operation as specified in the relevant C documentation. |
There was a problem hiding this comment.
I was thinking the same thing, but since most fcntl values are platform-dependent there probably isn't a good documentation link to use here.
| this is most likely to result in a segmentation violation or | ||
| a more subtle data corruption. |
There was a problem hiding this comment.
| this is most likely to result in a segmentation violation or | |
| a more subtle data corruption. | |
| it is most likely to result in a segmentation violation or | |
| a more subtle data corruption. |
Continues on from previous suggestion
Co-authored-by: Stan Ulbrych <[email protected]>
There was a problem hiding this comment.
Thank you for your suggestions, @StanFromIreland.
I fixed my own writing, but some parts were just copied from the old documentation, and I am not sure that changing them will not introduce some subtle change in semantic.
| :func:`struct.pack`. The binary data is copied to a buffer whose address is | ||
| :class:`bytes` object, or a string. | ||
| The type and the size of *arg* must match the type and the size of | ||
| the argument of the operation as specified in the relevant C documentation. |
There was a problem hiding this comment.
Depending on platform. Various manpages on Posix systems, some Microsoft links on Windows.
Doc/library/fcntl.rst
Outdated
| If the type or the size of *arg* does not match the type or the size | ||
| of the argument of the operation (for example, if an integer is | ||
| passed when a pointer is expected, or the information returned in | ||
| the buffer by the operating system is larger than 1024 bytes), | ||
| this is most likely to result in a segmentation violation or | ||
| a more subtle data corruption. |
There was a problem hiding this comment.
This was mainly the moved old documentation.
Co-authored-by: Stan Ulbrych <[email protected]>
| the argument is bytes it represents a binary structure, e.g. created by | ||
| :func:`struct.pack`. The binary data is copied to a buffer whose address is | ||
| header files. The argument *arg* can either be an integer value, a | ||
| :class:`bytes` object, or a string. |
There was a problem hiding this comment.
Looks like it accepts any readable buffer
There was a problem hiding this comment.
It may accept other buffers without bf_releasebuffer, but bytes is the only standard type. Read-only memoryview or mmap are not supported.
Co-authored-by: Jelle Zijlstra <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]>
|
Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13. |
…132765) (cherry picked from commit 5f50541) Co-authored-by: Serhiy Storchaka <[email protected]>
|
GH-132832 is a backport of this pull request to the 3.13 branch. |
… (GH-132832) (cherry picked from commit 5f50541) Co-authored-by: Serhiy Storchaka <[email protected]>
📚 Documentation preview 📚: https://cpython-previews--132765.org.readthedocs.build/