From: Hirohito Higashi Date: Thu, 2 Apr 2026 16:36:48 +0000 (+0000) Subject: runtime(doc): clarify term_start() I/O behavior for Unix pty and MS-Windows ConPTY X-Git-Tag: v9.2.0283~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0646047b68c5430473bc46aa9b031319db489b73;p=thirdparty%2Fvim.git 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 Signed-off-by: Hirohito Higashi Signed-off-by: Christian Brabandt --- diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt index b46899ceae..7a4f9cd537 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