1File::Tee(3)          User Contributed Perl Documentation         File::Tee(3)
2
3
4

NAME

6       File::Tee - replicate data sent to a Perl stream
7

SYNOPSIS

9         use File::Tee qw(tee);
10
11         # simple usage:
12         tee(STDOUT, '>', 'stdout.txt');
13
14         print "hello world\n";
15         system "ls";
16
17         # advanced usage:
18         my $pid = tee STDERR, { prefix => "err[$$]: ", reopen => 'my.log'};
19
20         print STDERR "foo\n";
21         system("cat /bad/path");
22

DESCRIPTION

24       This module is able to replicate data written to a Perl stream into
25       another streams. It is the Perl equivalent of the shell utility tee(1).
26
27       It is implemeted around "fork", creating a new process for every tee'ed
28       stream. That way, there are no problems handling the output generated
29       by external programs run with system or by XS modules that don't go
30       through perlio.
31
32   API
33       The following function can be imported from this module:
34
35       tee $fh, $target, ...
36           redirects a copy of the data written to $fh to one or several files
37           or streams.
38
39           "$target, ..." is a list of target streams specifications that can
40           be:
41
42           •   file names with optional mode specifications:
43
44                 tee STDOUT, '>> /tmp/out', '>> /tmp/out2';
45                 tee STDOUT, '>>', '/tmp/out', '/tmp/out2';
46
47               If the mode specification is a separate argument, it will
48               affect all the file names following and not just the nearest
49               one.
50
51               If mode "|-" is used as a separate argument, the rest of the
52               arguments are slurped as arguments for the pipe command:
53
54                  tee STDERR, '|-', 'grep', '-i', 'error';
55                  tee STDERR, '| grep -i error'; # equivalent
56
57               Valid modes are ">", ">>", ">&", ">>&" and "|-". The default
58               mode is ">>".
59
60               File handles can also be used as targets:
61
62                  open my $target1, '>>', '/foo/bar';
63                  ...
64                  tee STDOUT, $target1, $target2, ...;
65
66               Finally, code references can also be used as targets. The
67               callback will be invoked for every line written to the tee'ed
68               stream with the data in $_. It has to return a true value on
69               success or false if some error happens. Also, note that the
70               callback will be called from a different process.
71
72           •   hash references describing the targets
73
74               For instance:
75
76                 tee STDOUT, { mode => '>>', open => '/tmp/foo', lock => 1};
77
78               will copy the data sent to STDOUT to "/tmp/foo".
79
80               The attributes that can be included inside the hash are:
81
82               open => $file_name
83               reopen => $file_name
84                   sets the target file or stream. It can contain a mode
85                   specification and also be an array. For instance:
86
87                     tee STDOUT, { open => '>> /tmp/out' };
88                     tee STDOUT, { reopen => ['>>', '/tmp/out2'] };
89                     tee STDOUT, { open => '| grep foo > /tmp/out' };
90
91                   If "reopen" is used, the file or stream is reopen for every
92                   write operation. The mode will be forced to append after
93                   the first write.
94
95               mode => $mode
96                   Alternative way to specify the mode to open the target file
97                   or stream
98
99               lock => $bool
100                   When true, an exclusive lock is obtained on the target file
101                   before writing to it.
102
103               prefix => $txt
104                   Some text to be prepended to every line sent to the target
105                   file.
106
107                   For instance:
108
109                     tee STDOUT, { prefix => 'OUT: ', lock => 1, mode => '>>', open => '/tmp/out.txt' };
110                     tee STDERR, { prefix => 'ERR: ', lock => 1, mode => '>>', open => '/tmp/out.txt' };
111
112               preprocess => sub { ... }
113                   A callback function that can modify the data before it gets
114                   sent to the target file.
115
116                   For instance:
117
118                     sub hexdump {
119                       my $data = shift;
120                       my @out;
121                       while ($data =~ /(.{1,32})/smg) {
122                           my $line=$1;
123                           my @c= (( map { sprintf "%02x",$_ } unpack('C*', $line)),
124                                   (("  ") x 32))[0..31];
125                           $line=~s/(.)/ my $c=$1; unpack("c",$c)>=32 ? $c : '.' /egms;
126                           push @out, join(" ", @c, '|', $line), "\n";
127                       }
128                       join('', @out);
129                     }
130
131                     tee BINFH, { preprocess => \&hexdump, open => '/tmp/hexout'};
132
133               autoflush => $bool
134                   Sets autoflush mode for the target streams. Default is on.
135
136               ignore_errors => $bool
137                   By default, when writting to the targets, any error will
138                   close the tee'ed handle. This option allows to change that
139                   behaviour.
140
141               process => sub { ... }
142                   the callback will be called for every line read (see using
143                   code references as targets discussion above). This option
144                   can not be used at the same time as most other options
145                   (open, reopen, lock, autoflush, etc.).
146
147               begin => sub { ... }
148               end => sub { ... }
149                   Those functions are called on the forked process before the
150                   first write and when closing the handle respectively.
151
152                   For instance:
153
154                     my @capture;
155                     tee STDERR, { process => sub { push @capture, $_ },
156                                   end => sub { send_mail 'foo@bar.com', 'stderr capture', "@capture" } };
157
158           The funcion returns the PID for the newly created process.
159
160           Inside the "tee" pipe process created, data is readed honouring the
161           input record separator $/.
162
163           You could also want to set the tee'ed stream in autoflush mode:
164
165             open $fh, ...;
166
167             my $oldsel = select $fh;
168             $| = 1;
169             select $fh;
170
171             tee $fh, "> /tmp/log";
172

BUGS

174       Does not work on Windows (patches welcome).
175
176       Send bug reports by email or via the CPAN RT web <https://rt.cpan.org>.
177

SEE ALSO

179       IO::Capture
180
181       IO::Tee is a similar module implemented around tied file handles. Tee
182       allows to launch external processes capturing their output to some
183       files. IO::CaptureOutput allows to capture the output generated from a
184       child process or a subroutine.
185

187       Copyright (C) 2007, 2008, 2010, 2011 by Salvador Fandiño
188       (sfandino@yahoo.com)
189
190       This library is free software; you can redistribute it and/or modify it
191       under the same terms as Perl itself, either Perl version 5.8.8 or, at
192       your option, any later version of Perl 5 you may have available.
193
194
195
196perl v5.34.0                      2021-07-22                      File::Tee(3)
Impressum