[3.14] pythongh-140615: Update docstrings in the fcntl module (pythonGH-140619)

* Refer to bytes objects or bytes-like objects instead of strings.
* Remove backticks -- they do not have effect on formatting.
* Re-wrap lines to ensure the pydoc output fits in 80 coluimns.
* Remove references to the 1024 bytes limit.
(cherry picked from commit 6103770)

Co-authored-by: Serhiy Storchaka <[email protected]>

Author: serhiy-storchaka

Modules/clinic/fcntlmodule.c.h

@@ -41,22 +41,27 @@ fcntl.fcntl
     arg: object(c_default='NULL') = 0
     /
 
-Perform the operation `cmd` on file descriptor fd.
-
-The values used for `cmd` are operating system dependent, and are available
-as constants in the fcntl module, using the same names as used in
-the relevant C header files.  The argument arg is optional, and
-defaults to 0; it may be an int or a string.  If arg is given as a string,
-the return value of fcntl is a string of that length, containing the
-resulting value put in the arg buffer by the operating system.  The length
-of the arg string is not allowed to exceed 1024 bytes.  If the arg given
-is an integer or if none is specified, the result value is an integer
-corresponding to the return value of the fcntl call in the C code.
+Perform the operation cmd on file descriptor fd.
+
+The values used for cmd are operating system dependent, and are
+available as constants in the fcntl module, using the same names as used
+in the relevant C header files.  The argument arg is optional, and
+defaults to 0; it may be an integer, a bytes-like object or a string.
+If arg is given as a string, it will be encoded to binary using the
+UTF-8 encoding.
+
+If the arg given is an integer or if none is specified, the result value
+is an integer corresponding to the return value of the fcntl() call in
+the C code.
+
+If arg is given as a bytes-like object, the return value of fcntl() is a
+bytes object of that length, containing the resulting value put in the
+arg buffer by the operating system.
 [clinic start generated code]*/
 
 static PyObject *
 fcntl_fcntl_impl(PyObject *module, int fd, int code, PyObject *arg)
-/*[clinic end generated code: output=888fc93b51c295bd input=7955340198e5f334]*/
+/*[clinic end generated code: output=888fc93b51c295bd input=77340720f11665da]*/
 {
     int ret;
     int async_err = 0;
@@ -135,40 +140,39 @@ fcntl.ioctl
     mutate_flag as mutate_arg: bool = True
     /
 
-Perform the operation `request` on file descriptor `fd`.
+Perform the operation request on file descriptor fd.
 
-The values used for `request` are operating system dependent, and are available
-as constants in the fcntl or termios library modules, using the same names as
-used in the relevant C header files.
+The values used for request are operating system dependent, and are
+available as constants in the fcntl or termios library modules, using
+the same names as used in the relevant C header files.
 
-The argument `arg` is optional, and defaults to 0; it may be an int or a
-buffer containing character data (most likely a string or an array).
+The argument arg is optional, and defaults to 0; it may be an integer, a
+bytes-like object or a string.  If arg is given as a string, it will be
+encoded to binary using the UTF-8 encoding.
 
-If the argument is a mutable buffer (such as an array) and if the
-mutate_flag argument (which is only allowed in this case) is true then the
-buffer is (in effect) passed to the operating system and changes made by
-the OS will be reflected in the contents of the buffer after the call has
-returned.  The return value is the integer returned by the ioctl system
-call.
+If the arg given is an integer or if none is specified, the result value
+is an integer corresponding to the return value of the ioctl() call in
+the C code.
 
-If the argument is a mutable buffer and the mutable_flag argument is false,
-the behavior is as if a string had been passed.
+If the argument is a mutable buffer (such as a bytearray) and the
+mutate_flag argument is true (default) then the buffer is (in effect)
+passed to the operating system and changes made by the OS will be
+reflected in the contents of the buffer after the call has returned.
+The return value is the integer returned by the ioctl() system call.
 
-If the argument is an immutable buffer (most likely a string) then a copy
-of the buffer is passed to the operating system and the return value is a
-string of the same length containing whatever the operating system put in
-the buffer.  The length of the arg buffer in this case is not allowed to
-exceed 1024 bytes.
+If the argument is a mutable buffer and the mutable_flag argument is
+false, the behavior is as if an immutable buffer had been passed.
 
-If the arg given is an integer or if none is specified, the result value is
-an integer corresponding to the return value of the ioctl call in the C
-code.
+If the argument is an immutable buffer then a copy of the buffer is
+passed to the operating system and the return value is a bytes object of
+the same length containing whatever the operating system put in the
+buffer.
 [clinic start generated code]*/
 
 static PyObject *
 fcntl_ioctl_impl(PyObject *module, int fd, unsigned long code, PyObject *arg,
                  int mutate_arg)
-/*[clinic end generated code: output=f72baba2454d7a62 input=9c6cca5e2c339622]*/
+/*[clinic end generated code: output=f72baba2454d7a62 input=954fe75c208cc492]*/
 {
     /* We use the unsigned non-checked 'I' format for the 'code' parameter
        because the system expects it to be a 32bit bit field value
@@ -290,15 +294,15 @@ fcntl.flock
     operation as code: int
     /
 
-Perform the lock operation `operation` on file descriptor `fd`.
+Perform the lock operation on file descriptor fd.
 
 See the Unix manual page for flock(2) for details (On some systems, this
 function is emulated using fcntl()).
 [clinic start generated code]*/
 
 static PyObject *
 fcntl_flock_impl(PyObject *module, int fd, int code)
-/*[clinic end generated code: output=84059e2b37d2fc64 input=0bfc00f795953452]*/
+/*[clinic end generated code: output=84059e2b37d2fc64 input=ade68943e8599f0a]*/
 {
     int ret;
     int async_err = 0;
@@ -361,22 +365,22 @@ fcntl.lockf
 
 A wrapper around the fcntl() locking calls.
 
-`fd` is the file descriptor of the file to lock or unlock, and operation is one
-of the following values:
+fd is the file descriptor of the file to lock or unlock, and operation
+is one of the following values:
 
     LOCK_UN - unlock
     LOCK_SH - acquire a shared lock
     LOCK_EX - acquire an exclusive lock
 
 When operation is LOCK_SH or LOCK_EX, it can also be bitwise ORed with
-LOCK_NB to avoid blocking on lock acquisition.  If LOCK_NB is used and the
-lock cannot be acquired, an OSError will be raised and the exception will
-have an errno attribute set to EACCES or EAGAIN (depending on the operating
-system -- for portability, check for either value).
+LOCK_NB to avoid blocking on lock acquisition.  If LOCK_NB is used and
+the lock cannot be acquired, an OSError will be raised and the exception
+will have an errno attribute set to EACCES or EAGAIN (depending on the
+operating system -- for portability, check for either value).
 
-`len` is the number of bytes to lock, with the default meaning to lock to
-EOF.  `start` is the byte offset, relative to `whence`, to that the lock
-starts.  `whence` is as with fileobj.seek(), specifically:
+len is the number of bytes to lock, with the default meaning to lock to
+EOF.  start is the byte offset, relative to whence, to that the lock
+starts.  whence is as with fileobj.seek(), specifically:
 
     0 - relative to the start of the file (SEEK_SET)
     1 - relative to the current buffer position (SEEK_CUR)
@@ -386,7 +390,7 @@ starts.  `whence` is as with fileobj.seek(), specifically:
 static PyObject *
 fcntl_lockf_impl(PyObject *module, int fd, int code, PyObject *lenobj,
                  PyObject *startobj, int whence)
-/*[clinic end generated code: output=4985e7a172e7461a input=5480479fc63a04b8]*/
+/*[clinic end generated code: output=4985e7a172e7461a input=369bef4d7a1c5ff4]*/
 {
     int ret;
     int async_err = 0;