ioctl mutate_flag behavior in regard to the buffer size limit

[YuvalWeinbaum]

BPO	16834
Nosy	@vadmium

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2013-01-01.14:56:29.891>
labels = ['extension-modules', '3.8', '3.9', '3.10', 'docs']
title = 'ioctl mutate_flag behavior in regard to the buffer size limit'
updated_at = <Date 2020-11-06.22:43:18.137>
user = 'https://bugs.python.org/YuvalWeinbaum'

bugs.python.org fields:

activity = <Date 2020-11-06.22:43:18.137>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Extension Modules']
creation = <Date 2013-01-01.14:56:29.891>
creator = 'Yuval.Weinbaum'
dependencies = []
files = []
hgrepos = []
issue_num = 16834
keywords = []
message_count = 3.0
messages = ['178732', '223123', '238579']
nosy_count = 3.0
nosy_names = ['docs@python', 'martin.panter', 'Yuval.Weinbaum']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue16834'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

[YuvalWeinbaum]

In fcntl module, the documentation states the following regarding the mutate_flag in ioctl method:

---

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 as least as long as what the operating system wants to put there, things should work.
***

However, looking at the code (fcntlmodule.c) it seems that the 1024 bytes limitation is avoided when the mutate_flag is set to True (the opposite of what is stated in the doc).

[BreamoreBoy]

@yuval sorry about the delay in replying. Can a *nix person comment on this please as I stick with Windows.

[vadmium]

Looking at the C code, if a writable buffer is passed, mutate_arg is false, and the buffer is longer than 1024 bytes, then a ValueError is raised:

>>> ioctl(0, 0, bytearray(2048), False)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: ioctl string arg too long

So it seems the implementation does not match the documentation’s claim that “the 1024 byte limit . . . is avoided”. IMO this is an implementation bug.

But instead of (or in addition to) fixing it, maybe we could consider removing “mutate_flag” parameter altogether. It was originally added as a backwards compatibility helper for bpo-555817 in Python 2.3, and changed to True by default in Python 2.5.

[vadmium]

Also, the mutate_flag parameter should be documented as positional only, otherwise it is too tempting to try using it as a keyword

[serhiy-storchaka]

The documentation will be fixed in #132765, and the implementation may be changed in #132768.