The current code of thefcntl module is a little mess. This was caused particularly by the nature of the underlying C API (fcntl() andioctl() take an argument as a C int or a pointer to a structure, and the type of the argument, as well as the size of the structure is not explicitly specified, but depends on opcode and is platform depending), and particularly by the decades of incremental changes.

At Python level,fcntl() andioctl() take an optional argument which can be an integer, a string, or a mutable or immutable bytes-like object. The result can be an integer or a bytes object. The input mutable bytes-like object can be modified in-place inioctl(). Issues, differences and inconsistencies betweenfcntl() andioctl():

• ioctl() first try to interpret the argument as a mutable bytes-like object, then as a string or immutable bytes-like object, then as an integer.fcntl() does the same except trying a mutable bytes-like object. Raising and silencing exceptions is not particularly efficient, and silencing arbitrary exceptions is not good.
• fcntl() andioctl() accept string argument. This looks like an unintentional side effect in Python 2 which was not fixed in Python 3. I do not know any operation code which takes a string argument -- they take binary structures. Even if there is an operation which takes a char array, most likely it should be encoded using filesystem encoding instead of UTF-8, sobytes is more preferable thanstr. String argument should be deprecated.
• ioctl() makes the temporary buffer null-terminated, butfcntl() does not.
• ioctl() has themutate_arg parameter, butfcntl() does not, even if some operations mutate argument.
• ioctl() copies the content of the mutable bytes-like object to a temporary buffer ifmutate_arg is true and it fits in a buffer, and then copies it back. It was needed when the parsing code used "w#", because the object could be resized after releasing the GIL. And it was wrong, because copying back will not work after resizing. But now "w*" is used ("w#" no longer supported), so no copying to temporary buffer is needed.
• ioctl() does not release the GIL when call the Cioctl() if the mutable bytes-like object does not fit in the temporary buffer. It can, for reasons described above.
• ioctl() accepts opcode asunsigned intunsigned long,fcntl() accepts onlyint.fcntl() accepts the integer argument asunsigned int,ioctl() accepts onlyint. Using an unsigned format makes the code more error-prone (Deprecate accepting out of range values for unsigned integers in PyArg_Parse #132629 should mitigate this), but makes it more usable if some opcode or value constants in C has the MSB set. I think that both function should acceptunsigned int (unsigned long?) for both arguments.
• fcntl() automatically retries on EINTR,ioctl() raises an OSError.

Linked PRs

• gh-132742: Add more tests for fcntl.ioctl() #132756
• [3.13] gh-132742: Add more tests for fcntl.ioctl() (GH-132756) #132764
• gh-132742: Update documentation for the fcntl module #132765
• gh-132742: Refactor fcntl.fcntl() and fcntl.ioctl() #132768
• gh-132742: Improve tests for fcntl.ioctl() #132791
• [3.13] gh-132742: Update documentation for the fcntl module (GH-132765) #132832
• [3.13] gh-132742: Improve tests for fcntl.ioctl() (GH-132791) #133066
• gh-132742: Fix newly added tcflush() tests on Android #133070
• [3.13] gh-132742: Fix newly added tcflush() tests on Android (GH-133070) #133104