pythongh-132742: Update documentation for the fcntl module

Author: serhiy-storchaka

Doc/library/fcntl.rst

@@ -89,20 +89,32 @@ The module defines the following functions:
    for *cmd* are operating system dependent, and are available as constants
    in the :mod:`fcntl` module, using the same names as used in the relevant C
    header files. The argument *arg* can either be an integer value, or a
-   :class:`bytes` object. With an integer value, the return value of this
-   function is the integer return value of the C :c:func:`fcntl` call.  When
-   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
+   :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.
+
+   With an integer value, the return value of this function is the integer
+   return value of the C :c:func:`fcntl` call.
+
+   When the argument is bytes, it represents a binary structure,
+   e.g. created by :func:`struct.pack`.
+   A string value is encoded to binary using the UTF-8 encoding.
+   The binary data is copied to a buffer whose address is
    passed to the C :c:func:`fcntl` call.  The return value after a successful
    call is the contents of the buffer, converted to a :class:`bytes` object.
    The length of the returned object will be the same as the length of the
-   *arg* argument. This is limited to 1024 bytes. If 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.
+   *arg* argument. This is limited to 1024 bytes.
 
    If the :c:func:`fcntl` call fails, an :exc:`OSError` is raised.
 
+   .. note::
+      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.
+
    .. audit-event:: fcntl.fcntl fd,cmd,arg fcntl.fcntl
 
 
@@ -111,36 +123,41 @@ The module defines the following functions:
    This function is identical to the :func:`~fcntl.fcntl` function, except
    that the argument handling is even more complicated.
 
-   The *request* parameter is limited to values that can fit in 32-bits.
+   The *request* parameter is limited to values that can fit in 32-bits
+   or 64-bits, depending on platform.
    Additional constants of interest for use as the *request* argument can be
    found in the :mod:`termios` module, under the same names as used in
    the relevant C header files.
 
-   The parameter *arg* can be one of an integer, an object supporting the
-   read-only buffer interface (like :class:`bytes`) or an object supporting
-   the read-write buffer interface (like :class:`bytearray`).
+   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.
 
-   In all but the last case, behaviour is as for the :func:`~fcntl.fcntl`
+   If *arg* does not support the read-write buffer interface or
+   a *mutate_flag* is false, behaviour is as for the :func:`~fcntl.fcntl`
    function.
 
-   If a mutable buffer is passed, then the behaviour is determined by the value of
-   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 --
-   so long as the buffer you pass is at least as long as what the operating system
-   wants to put there, things should work.
-
-   If *mutate_flag* is true (the default), then the buffer is (in effect) passed
-   to the underlying :func:`ioctl` system call, the latter's return code is
+   If *arg* supports the read-write buffer interface (like :class:`bytearray`)
+   and *mutate_flag* is true (the default), then the buffer is (in effect) passed
+   to the underlying :c:func:`!ioctl` system call, the latter's return code is
    passed back to the calling Python, and the buffer's new contents reflect the
-   action of the :func:`ioctl`.  This is a slight simplification, because if the
+   action of the :c:func:`ioctl`.  This is a slight simplification, because if the
    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
+      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,
+      or the size of the mutable bytes-like object is too small),
+      this is most likely to result in a segmentation violation or
+      a more subtle data corruption.
+
    An example::
 
       >>> import array, fcntl, struct, termios, os