## Summary

`redirects.py` previously disabled stdout/stderr redirection on Windows with a warning, affecting all Windows GPU users (both NVIDIA CUDA and AMD ROCm).

This PR adds a proper Windows implementation that works by performing a four-layer redirect:

1. `sys.stdout`/`sys.stderr` - rewired to a new TextIOWrapper so Python's `print()` writes to the destination file
2. CRT fd via `_dup2` - captures C-level writes through UCRT FILE* handles
3. Win32 `SetStdHandle` - captures native code using WriteFile/WriteConsole directly, including GPU runtime output
4. `fflush` before each switch - prevents lost output from CRT buffering

`os.dup2` is intentionally not used on Windows as it silently corrupts file descriptors backed by console HANDLEs. The CRT's own `_dup`/`_dup2` from `ucrtbase` are used instead, which correctly handle the console-to-file transition.

The Linux code path is functionally unchanged.

## Tested on

- Windows 11, Python `3.12`, ROCm `7.12.0a`, PyTorch `2.12.0a0`, AMD Radeon RX 9060 XT
- Verified all four cases: Python print, C-level _write, stderr redirect, and stdout restore with the following test script:

<details>
<summary>test_redirect.py</summary>

```python
import ctypes
import sys
sys.path.insert(0, r"path/to/torch/distributed/elastic/multiprocessing")

from redirects import redirect_stdout, redirect_stderr

with redirect_stdout("test_stdout.log"):
    print("hello from python stdout")
with open("test_stdout.log") as f:
    assert "hello from python stdout" in f.read()
print("Test 1 PASSED - Python print")

with redirect_stdout("test_cprintf.log"):
    ucrtbase = ctypes.CDLL("ucrtbase")
    msg = b"hello from C _write\n"
    ucrtbase._write(1, msg, len(msg))
with open("test_cprintf.log") as f:
    assert "hello from C _write" in f.read()
print("Test 2 PASSED - C-level _write")

with redirect_stderr("test_stderr.log"):
    print("hello from stderr", file=sys.stderr)
with open("test_stderr.log") as f:
    assert "hello from stderr" in f.read()
print("Test 3 PASSED - stderr")

with redirect_stdout("test_restore.log"):
    print("inside redirect")
print("Test 4 PASSED - stdout restored")
```

Output:
```
Test 1 PASSED - Python print
Test 2 PASSED - C-level _write
Test 3 PASSED - stderr
Test 4 PASSED - stdout restored
```

</details>

## Does this change break backward compatibility?

No. Linux behavior is identical to before. On Windows, redirects now work instead of being silently skipped.

## Minor housekeeping
Fixed a pre-existing typo in the Linux docstring (missing closing paren in the usage example) and normalized the `Usage:` block to `Usage::` per RST convention.

Pull Request resolved: #176789
Approved by: https://github.com/jeffdaily

Co-authored-by: Xia-Weiwen <12522207+Xia-Weiwen@users.noreply.github.com>

…6789)

## Summary

`redirects.py` previously disabled stdout/stderr redirection on Windows with a warning, affecting all Windows GPU users (both NVIDIA CUDA and AMD ROCm).

This PR adds a proper Windows implementation that works by performing a four-layer redirect:

1. `sys.stdout`/`sys.stderr` - rewired to a new TextIOWrapper so Python's `print()` writes to the destination file
2. CRT fd via `_dup2` - captures C-level writes through UCRT FILE* handles
3. Win32 `SetStdHandle` - captures native code using WriteFile/WriteConsole directly, including GPU runtime output
4. `fflush` before each switch - prevents lost output from CRT buffering

`os.dup2` is intentionally not used on Windows as it silently corrupts file descriptors backed by console HANDLEs. The CRT's own `_dup`/`_dup2` from `ucrtbase` are used instead, which correctly handle the console-to-file transition.

The Linux code path is functionally unchanged.

## Tested on

- Windows 11, Python `3.12`, ROCm `7.12.0a`, PyTorch `2.12.0a0`, AMD Radeon RX 9060 XT
- Verified all four cases: Python print, C-level _write, stderr redirect, and stdout restore with the following test script:

<details>
<summary>test_redirect.py</summary>

```python
import ctypes
import sys
sys.path.insert(0, r"path/to/torch/distributed/elastic/multiprocessing")

from redirects import redirect_stdout, redirect_stderr

with redirect_stdout("test_stdout.log"):
    print("hello from python stdout")
with open("test_stdout.log") as f:
    assert "hello from python stdout" in f.read()
print("Test 1 PASSED - Python print")

with redirect_stdout("test_cprintf.log"):
    ucrtbase = ctypes.CDLL("ucrtbase")
    msg = b"hello from C _write\n"
    ucrtbase._write(1, msg, len(msg))
with open("test_cprintf.log") as f:
    assert "hello from C _write" in f.read()
print("Test 2 PASSED - C-level _write")

with redirect_stderr("test_stderr.log"):
    print("hello from stderr", file=sys.stderr)
with open("test_stderr.log") as f:
    assert "hello from stderr" in f.read()
print("Test 3 PASSED - stderr")

with redirect_stdout("test_restore.log"):
    print("inside redirect")
print("Test 4 PASSED - stdout restored")
```

Output:
```
Test 1 PASSED - Python print
Test 2 PASSED - C-level _write
Test 3 PASSED - stderr
Test 4 PASSED - stdout restored
```

</details>

## Does this change break backward compatibility?

No. Linux behavior is identical to before. On Windows, redirects now work instead of being silently skipped.

## Minor housekeeping
Fixed a pre-existing typo in the Linux docstring (missing closing paren in the usage example) and normalized the `Usage:` block to `Usage::` per RST convention.

Pull Request resolved: pytorch#176789
Approved by: https://github.com/jeffdaily

…6789)

## Summary

`redirects.py` previously disabled stdout/stderr redirection on Windows with a warning, affecting all Windows GPU users (both NVIDIA CUDA and AMD ROCm).

This PR adds a proper Windows implementation that works by performing a four-layer redirect:

1. `sys.stdout`/`sys.stderr` - rewired to a new TextIOWrapper so Python's `print()` writes to the destination file
2. CRT fd via `_dup2` - captures C-level writes through UCRT FILE* handles
3. Win32 `SetStdHandle` - captures native code using WriteFile/WriteConsole directly, including GPU runtime output
4. `fflush` before each switch - prevents lost output from CRT buffering

`os.dup2` is intentionally not used on Windows as it silently corrupts file descriptors backed by console HANDLEs. The CRT's own `_dup`/`_dup2` from `ucrtbase` are used instead, which correctly handle the console-to-file transition.

The Linux code path is functionally unchanged.

## Tested on

- Windows 11, Python `3.12`, ROCm `7.12.0a`, PyTorch `2.12.0a0`, AMD Radeon RX 9060 XT
- Verified all four cases: Python print, C-level _write, stderr redirect, and stdout restore with the following test script:

<details>
<summary>test_redirect.py</summary>

```python
import ctypes
import sys
sys.path.insert(0, r"path/to/torch/distributed/elastic/multiprocessing")

from redirects import redirect_stdout, redirect_stderr

with redirect_stdout("test_stdout.log"):
    print("hello from python stdout")
with open("test_stdout.log") as f:
    assert "hello from python stdout" in f.read()
print("Test 1 PASSED - Python print")

with redirect_stdout("test_cprintf.log"):
    ucrtbase = ctypes.CDLL("ucrtbase")
    msg = b"hello from C _write\n"
    ucrtbase._write(1, msg, len(msg))
with open("test_cprintf.log") as f:
    assert "hello from C _write" in f.read()
print("Test 2 PASSED - C-level _write")

with redirect_stderr("test_stderr.log"):
    print("hello from stderr", file=sys.stderr)
with open("test_stderr.log") as f:
    assert "hello from stderr" in f.read()
print("Test 3 PASSED - stderr")

with redirect_stdout("test_restore.log"):
    print("inside redirect")
print("Test 4 PASSED - stdout restored")
```

Output:
```
Test 1 PASSED - Python print
Test 2 PASSED - C-level _write
Test 3 PASSED - stderr
Test 4 PASSED - stdout restored
```

</details>

## Does this change break backward compatibility?

No. Linux behavior is identical to before. On Windows, redirects now work instead of being silently skipped.

## Minor housekeeping
Fixed a pre-existing typo in the Linux docstring (missing closing paren in the usage example) and normalized the `Usage:` block to `Usage::` per RST convention.

Pull Request resolved: pytorch#176789
Approved by: https://github.com/jeffdaily

…6789)

## Summary

`redirects.py` previously disabled stdout/stderr redirection on Windows with a warning, affecting all Windows GPU users (both NVIDIA CUDA and AMD ROCm).

This PR adds a proper Windows implementation that works by performing a four-layer redirect:

1. `sys.stdout`/`sys.stderr` - rewired to a new TextIOWrapper so Python's `print()` writes to the destination file
2. CRT fd via `_dup2` - captures C-level writes through UCRT FILE* handles
3. Win32 `SetStdHandle` - captures native code using WriteFile/WriteConsole directly, including GPU runtime output
4. `fflush` before each switch - prevents lost output from CRT buffering

`os.dup2` is intentionally not used on Windows as it silently corrupts file descriptors backed by console HANDLEs. The CRT's own `_dup`/`_dup2` from `ucrtbase` are used instead, which correctly handle the console-to-file transition.

The Linux code path is functionally unchanged.

## Tested on

- Windows 11, Python `3.12`, ROCm `7.12.0a`, PyTorch `2.12.0a0`, AMD Radeon RX 9060 XT
- Verified all four cases: Python print, C-level _write, stderr redirect, and stdout restore with the following test script:

<details>
<summary>test_redirect.py</summary>

```python
import ctypes
import sys
sys.path.insert(0, r"path/to/torch/distributed/elastic/multiprocessing")

from redirects import redirect_stdout, redirect_stderr

with redirect_stdout("test_stdout.log"):
    print("hello from python stdout")
with open("test_stdout.log") as f:
    assert "hello from python stdout" in f.read()
print("Test 1 PASSED - Python print")

with redirect_stdout("test_cprintf.log"):
    ucrtbase = ctypes.CDLL("ucrtbase")
    msg = b"hello from C _write\n"
    ucrtbase._write(1, msg, len(msg))
with open("test_cprintf.log") as f:
    assert "hello from C _write" in f.read()
print("Test 2 PASSED - C-level _write")

with redirect_stderr("test_stderr.log"):
    print("hello from stderr", file=sys.stderr)
with open("test_stderr.log") as f:
    assert "hello from stderr" in f.read()
print("Test 3 PASSED - stderr")

with redirect_stdout("test_restore.log"):
    print("inside redirect")
print("Test 4 PASSED - stdout restored")
```

Output:
```
Test 1 PASSED - Python print
Test 2 PASSED - C-level _write
Test 3 PASSED - stderr
Test 4 PASSED - stdout restored
```

</details>

## Does this change break backward compatibility?

No. Linux behavior is identical to before. On Windows, redirects now work instead of being silently skipped.

## Minor housekeeping
Fixed a pre-existing typo in the Linux docstring (missing closing paren in the usage example) and normalized the `Usage:` block to `Usage::` per RST convention.

Pull Request resolved: pytorch#176789
Approved by: https://github.com/jeffdaily