improve documentation around scalar/tied handles
David Golden
12 years ago
| 579 | 579 | *Scalar filehandles* |
| 580 | 580 | |
| 581 | 581 | If STDOUT or STDERR are reopened to scalar filehandles prior to the call to |
| 582 | {capture} or {tee}, then Capture::Tiny will override the output filehandle for the | |
| 583 | duration of the {capture} or {tee} call and then send captured output to the | |
| 584 | output filehandle after the capture is complete. (Requires Perl 5.8) | |
| 582 | {capture} or {tee}, then Capture::Tiny will override the output filehandle for | |
| 583 | the duration of the {capture} or {tee} call and then, for {tee}, send captured | |
| 584 | output to the output filehandle after the capture is complete. (Requires Perl | |
| 585 | 5.8) | |
| 585 | 586 | |
| 586 | 587 | Capture::Tiny attempts to preserve the semantics of STDIN opened to a scalar |
| 587 | reference. | |
| 588 | reference, but note that external processes will not be able to read from such | |
| 589 | a handle. Capture::Tiny tries to ensure that external processes will read from | |
| 590 | the null device instead, but this is not guaranteed. | |
| 588 | 591 | |
| 589 | 592 | *Tied output filehandles* |
| 590 | 593 | |
| 604 | 607 | Capture::Tiny attempts to preserve the semantics of tied STDIN, but this is not |
| 605 | 608 | entirely stable or portable. For example: |
| 606 | 609 | |
| 607 | * Capturing or teeing with STDIN tied is broken on Windows | |
| 608 | * [FCGI] has been reported as having a pathological tied filehandle implementation | |
| 609 | that causes fatal (and hard to diagnose) errors | |
| 610 | * Trying does not affect how external processes read data | |
| 611 | * Capturing or teeing with STDIN tied has been reported broken on Windows | |
| 610 | 612 | |
| 611 | 613 | Unless having STDIN tied is crucial, it may be safest to localize STDIN when |
| 612 | 614 | capturing: |