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 <[email protected]> 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 <[email protected]> Signed-off-by: Hirohito Higashi <[email protected]> Signed-off-by: Christian Brabandt <[email protected]> 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 -- -- You received this message from the "vim_dev" maillist. Do not top-post! Type your reply below the text you are replying to. For more information, visit http://www.vim.org/maillist.php --- You received this message because you are subscribed to the Google Groups "vim_dev" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion visit https://groups.google.com/d/msgid/vim_dev/E1w8LAH-000m9r-3w%40256bit.org.
