<type>documentation</type>
<domain>debug</domain>
<id>debug-process-i-o</id>
<title>Debug Process I/O</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>all</product>

~~~if WING101:
Debug process output from ``print()`` or any writes to ``stdout`` or ``stderr`` appears in
the `Debug I/O <script:show_panel#panel_type="debug-io">`__ tool. This is also where you
enter keyboard input, if your debug program requests any with ``input()`` or by reading 
from ``stdin``.
~~~

~~~if not WING101: 
For a debug process launched from Wing, I/O associated with ``print()``, writing to
``stdout`` or ``stderr``, calls to ``input()``, or reads from ``stdin``, always occurs in 
the `Debug I/O <script:show_panel#panel_type="debug-io">`__ tool, unless an external 
console has been configured as described in `External I/O Consoles
<ref:debug/external-i-o-consoles>`__.

Debug processes launched outside of Wing, using ``wingdbstub``, always do I/O through the
environment from which they were launched, whether that's a console window, web server, or
any other I/O environment.

The code that services debug process I/O does two things: (1) any waits on ``sys.stdin``
are multiplexed with servicing of the debug network socket, so that the debug process
remains responsive to Wing even while waiting for keyboard input, and (2) if the debug
process was launched from Wing, I/O is redirected over the network to the IDE.

Multiplexing I/O can cause problems in some code.  See `Debug Process I/O 
Multiplexing <ref:debug/debug-i-o-multiplexing>`__ for details.
~~~

~~~if WINGPRO:
If multiple debug processes are active, Wing creates one output buffer for each process
launched from the IDE and the process selected in the top left of the tool may be used
to move between them.

When commands are typed in the `Debug Console <ref:debug/debug-console>`__ in Wing
Pro, I/O is redirected temporarily to the ``Debug Console`` only during the time that the
command is being processed.
~~~

Options
-------

The following options are available in the ``Options`` menu in the ``Debug I/O`` tool:

**Clear** clears the contents of the current output buffer.

**Close All Terminated** unconditionally closes all output buffers for debug processes that 
have been terminated.

**Wrap Lines** causes long lines to be wrapped in the display.

**Never Auto-Show** prevents Wing from ever automatically showing the ``Debug I/O`` tool.

**Always Auto-Show on Output** causes Wing to automatically show the ``Debug I/O`` tool
when any output is received from the debug process.

**Auto-Show on First Output** causes Wing to automatically show the ``Debug I/O`` tool
only the first time output is received from a debug process.

**Auto-Focus for Input** causes Wing to show the Debug I/O tool and set focus into the
I/O buffer whenever a debug process is waiting for keyboard input.
~~~if not WING101:
This is disabled by default in Wing Personal and Wing Pro and disabling the `Debugger >
Advanced > Use sys.stdin Wrapper <script:show_preferences_gui#prefname="debug.use-stdin-wrapper">`__ 
preference prevents this feature from working.
~~~

~~~if WINGPRO:
**Retain History** causes Wing to retain old output buffers, up to the number
configured with the `Files > Max Recent Items <script:show_preferences_gui#prefname="gui.max-recent-files">`__
preference.  When this is unchecked, only one buffer is retained.  Old buffers
are cleared automatically only when a new debug process is started, to avoid losing
output for a related group of partially-running processes.  Old buffers can be cleared 
unconditionally at any time with ``Close All Terminated`` from the ``Debug I/O`` tool's 
``Options menu``.

**Show Child Processes** enables including child processes in the process selector.
Otherwise only the top-level parent processes are shown.
~~~

~~~if not WING101:
**Configure External Console** allows replacing Wing's builtin ``Debug I/O`` tool
with an OS-appropriate console run in a separate window.  See `External I/O Consoles
<ref:debug/external-i-o-consoles>`__ for details.

**Configure Encoding** allows setting the encoding used for I/O to debug processes.
This must be set to match the expectation of the debug process.
~~~

**Show Debug I/O Documentation** displays this documentation page.
