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.

Raspunde prin e-mail lui