.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Test::Trap::Builder::SystemSafe 3"
.TH Test::Trap::Builder::SystemSafe 3 2025-12-14 "perl v5.42.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Test::Trap::Builder::SystemSafe \- "Safe" capture strategies using File::Temp
.SH VERSION
.IX Header "VERSION"
Version 0.3.5
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides capture strategies \fIsystemsafe\fR, based on
File::Temp, for the trap\*(Aqs output layers.  These strategies insists on
reopening the output file handles with the same descriptors, and
therefore, unlike Test::Trap::Builder::TempFile and
Test::Trap::Builder::PerlIO, is able to trap output from forked\-off
processes, including \fBsystem()\fR.
.PP
The import accepts a name (as a string; default \fIsystemsafe\fR) and
options (as a hashref; by default empty), and registers a capture
strategy with that name and a variant implementation based on the
options.
.PP
Note that you may specify different strategies for each output layer
on the trap.
.PP
See also Test::Trap (:stdout and :stderr) and
Test::Trap::Builder (output_layer).
.SH OPTIONS
.IX Header "OPTIONS"
The following options are recognized:
.SS preserve_io_layers
.IX Subsection "preserve_io_layers"
A boolean, indicating whether to apply to the handles writing to and
reading from the tempfile, the same perlio layers as are found on the
to\-be\-trapped output handle.
.SS io_layers
.IX Subsection "io_layers"
A colon\-separated string representing perlio layers to be applied to
the handles writing to and reading from the tempfile.
.PP
If the \fIpreserve_io_layers\fR option is set, these perlio layers will
be applied on top of the original (preserved) perlio layers.
.SH CAVEATS
.IX Header "CAVEATS"
Using File::Temp, we need privileges to create tempfiles.
.PP
We need disk space for the output of every trap (it should clean up
after the trap is sprung).
.PP
Disk access may be slow \-\- certainly compared to the in\-memory files
of PerlIO.
.PP
If the file handle we try to trap using this strategy is on an
in\-memory file, it would not be available to other processes in any
case.  Rather than change the semantics of the trapped code or
silently fail to trap output from forked\-off processes, we just raise
an exception in this case.
.PP
If there is another file handle with the same descriptor (f ex after
an \f(CW\*(C`open OTHER, \*(Aq>&=\*(Aq, THIS\*(C'\fR), we can\*(Aqt get that file descriptor.
Rather than silently fail, we again raise an exception.
.PP
If the options specify (explicitly or via preserve on handles with)
perlio custom layers, they may (or may not) fail to apply to the
tempfile read and write handles.
.PP
Threads?  No idea.  It might even work correctly.
.SH BUGS
.IX Header "BUGS"
Please report any bugs or feature requests directly to the author.
.SH AUTHOR
.IX Header "AUTHOR"
Eirik Berg Hanssen, \f(CW\*(C`<ebhanssen@cpan.org>\*(C'\fR
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2006\-2014 Eirik Berg Hanssen, All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.