[tagilman]

Fixes #1070.

Problem

On Python 3.14, invoke.terminals.bytes_to_read() raises
SystemError: buffer overflow:

fionread = fcntl.ioctl(input_, termios.FIONREAD, b"  ")  # 2-byte buffer
return int(struct.unpack("h", fionread)[0])

FIONREAD writes back a C int (4 bytes), but the buffer passed is only
2 bytes. Before 3.14, CPython's fcntl.ioctl copied an immutable buffer
into a 1024-byte static scratch buffer and returned only the first
len(buf) bytes, so the undersized buffer was silently tolerated
(and the 4-byte result truncated to 2). Python 3.14 tightened
fcntl.ioctl to raise SystemError when the ioctl would write more
bytes than the passed buffer holds (cpython#144206).

This is the same root cause as #1038, whose fix (#1040) only touched
the TIOCGWINSZ path in _pty_size() and did not address this second
occurrence in bytes_to_read(). It bites any Runner.run(pty=True) from
a TTY-attached process on 3.14.

Fix

Size the buffer to a full native int and unpack it as one:

buf = struct.pack("i", 0)
fionread = fcntl.ioctl(input_, termios.FIONREAD, buf)
return int(struct.unpack("i", fionread)[0])

Tests

• Implemented the previously-skip()ped
  terminals.bytes_to_read_.returns_FIONREAD_result_when_stream_is_a_tty
  as a real regression test that drives the actual ioctl against a
  pty (a mock can't reproduce 3.14's buffer-size check). It asserts the
  call does not raise, returns a non-negative int, and — to guard against
  reintroducing the undersized buffer — that the buffer handed to
  FIONREAD is int-sized. Verified it fails with SystemError: buffer overflow on 3.14 without the fix and passes with it.
• Updated the FIONREAD mock in tests/runners.py
  (reads_FIONREAD_bytes_from_stdin_when_fileno) to struct.pack("i", …)
  to match.

Verified on Python 3.14.6 and 3.12.13 (tests/terminals.py: 7 passed,
1 skipped on both). flake8 clean.

Note: the broader test suite still has unrelated Python 3.14 failures
(e.g. tests/_util.py's fakeread harness hardcodes fd numbers) that are
independent of this change and part of the wider 3.14-support effort
(#1015 / #1052); this PR is scoped to #1070 and introduces no new
failures (it turns 7 previously-failing FIONREAD-dependent tests green).

Thanks to @RemiDesgrange for the report and root-cause analysis in #1070.

[hefee]

Unfortunately there are 3 pull requests try to fix the same issue, so nobody has looked if others already have started to fix and try to improve one pr:
#1053 , #1074, #1077
from the style of the MR I would say: #1074 and #1077 are created with the help of AI.

[Mukller]

Verified as far as Windows allows (real CPython 3.14.5 via uv, editable install of the branch):

• bytes_to_read guard paths work on 3.14/Windows: non-tty StringIO and fileno-less objects return 1 without touching the ioctl branch.
• The size claim is arithmetically exact: the old buffer b" " is 2 bytes, while FIONREAD writes back a C int (4 bytes) — so on 3.14's stricter fcntl.ioctl this is a genuine buffer mismatch, not a style issue. The fix's struct.pack("i", 0) / unpack("i", ...) pair is symmetric at exactly 4 bytes.
• The change mirrors the maintainer-accepted TIOCGWINSZ fixes (#1038/#1040) — same root cause class, same remedy, and per the PR description deliberately scoped away from that earlier patch.

Honest limits: the failing path requires a POSIX tty + fcntl, which I cannot exercise on Windows; their CI (Linux, including 3.14 jobs) is green, and the updated fake_ioctl in tests/runners.py now packs "i" consistently with the production code, so the mocked round-trip validates the new sizing.

Approving — this unblocks every POSIX user on 3.14, where the current release raises SystemError on any tty-driven read.

[canavandl]

We tested this fix on Python 3.14 through our CLI’s Fabric/Paramiko interactive SSH path, and it resolves the input hang. Both Invoke 2.2.1 and 3.0.3 reproduce the failure; this PR passes.

What’s the plan for merging this? Would a 2.x backport be possible, given Fabric 3.2.3’s invoke<3.0 constraint?

[canavandl]

Resolved the issue in our CLI's Fabric/Paramikok interactive SSH path.