Commit: runtime(doc): clarify term_start() I/O behavior for Unix pty and MS-Windows ConPTY

[Christian Brabandt]

runtime(doc): clarify term_start() I/O behavior for Unix pty and MS-Windows ConPTY

Commit: https://github.com/vim/vim/commit/0646047b68c5430473bc46aa9b031319db489b73
Author: Hirohito Higashi <h.eas...@gmail.com>
Date: Thu Apr 2 16:36:48 2026 +0000

runtime(doc): clarify term_start() I/O behavior for Unix pty and MS-Windows ConPTY

Explain how stdin/stdout/stderr are connected in term_start():
- On Unix, they default to pty; only "err_cb" switches stderr to a pipe,
which may cause output order differences due to buffering.
- On MS-Windows with ConPTY, they are always pipes and stdout/stderr
share the same pipe, so "err_cb" cannot separate them.

related: #16354

Co-authored-by: Yasuhiro Matsumoto <matt...@gmail.com>
Signed-off-by: Hirohito Higashi <h.eas...@gmail.com>
Signed-off-by: Christian Brabandt <c...@256bit.org>

diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index b46899cea..7a4f9cd53 100644
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -1,4 +1,4 @@
-*terminal.txt* For Vim version 9.2. Last change: 2026 Mar 12
+*terminal.txt* For Vim version 9.2. Last change: 2026 Apr 02


VIM REFERENCE MANUAL by Bram Moolenaar
@@ -944,9 +944,26 @@ term_start({cmd} [, {options}]) *term_start()*
"in_io", "in_top", "in_bot", "in_name", "in_buf"
"out_io", "out_name", "out_buf", "out_modifiable", "out_msg"
"err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
- However, at least one of stdin, stdout or stderr must be
- connected to the terminal. When I/O is connected to the
- terminal then the callback function for that part is not used.
+ On Unix:
+ stdin, stdout, and stderr are connected to a pty by default,
+ since bidirectional communication with the terminal is
+ required. Setting "out_cb" does not switch stdout from the
+ pty to a pipe. Only setting "err_cb" switches stderr to a
+ pipe.
+ Note: Since a pty is line-buffered and a pipe is
+ block-buffered, the order of output between stdout and stderr
+ may not be preserved. Without "err_cb", stderr uses the same
+ pty as stdout, so the output order is preserved but stdout and
+ stderr cannot be distinguished.
+
+ On MS-Windows with |ConPTY|:
+ stdin, stdout, and stderr are always connected through pipes
+ to the pseudo console, regardless of callback settings.
+ Since stdout and stderr share the same pipe, they cannot be
+ separated by "err_cb".
+ This is because the CreatePseudoConsole() API only accepts one
+ input and one output handle, with no separate handle for
+ stderr.

There are extra options:
"term_name" name to use for the buffer name, instead