.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IPC::Pipeline 3"
.TH IPC::Pipeline 3 "2014-09-13" "perl v5.16.3" "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"
IPC::Pipeline \- Create a shell\-like pipeline of many running commands
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use IPC::Pipeline;
\&
\&    my @pids = pipeline( my $first_child_in, my $last_child_out, my $err,
\&        [qw(filter1 args)],
\&        sub { filter2(); return 0 },
\&        [qw(filter3 args)],
\&        ...
\&        [qw(commandN args)]
\&    );
\&
\&    ... do stuff ...
\&
\&    my %statuses = map {
\&        waitpid($_, 0);
\&        $_ => ($? >> 8);
\&    } @pids;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBIPC::Pipeline\fR exports a single function \f(CW\*(C`pipeline()\*(C'\fR.
.PP
Similar in calling convention to IPC::Open3, \f(CW\*(C`pipeline()\*(C'\fR spawns N children,
connecting the first child to the \f(CW$first_child_in\fR handle, the final child to
\&\f(CW$last_child_out\fR, and each child to a shared standard error handle, \f(CW$err\fR.
Each subsequent filter specified causes a new process to be \f(CW\*(C`fork()\*(C'\fRed.  Each
process is linked to the last with a file descriptor pair created by \f(CW\*(C`pipe()\*(C'\fR,
using \f(CW\*(C`dup2()\*(C'\fR to chain each process' standard input to the last standard output.
.PP
\&\fBIPC::Pipeline\fR does not work on \fBMSWin32\fR, but it works on \fBcygwin\fR.
.SS "\s-1FEATURES\s0"
.IX Subsection "FEATURES"
\&\fBIPC::Pipeline\fR accepts external commands to be executed in the form of \s-1ARRAY\s0
references containing the command name and each argument, as well as \s-1CODE\s0
references that are executed within their own processes as well, each as
independent parts of a pipeline.
.PP
\fI\s-1ARRAY REFS\s0\fR
.IX Subsection "ARRAY REFS"
.PP
When a filter is passed in the form of an \s-1ARRAY\s0 containing an external system
command, each such item is executed in its own subprocess in the following
manner.
.PP
.Vb 1
\&    exec(@$filter) or die("Cannot exec(): $!");
.Ve
.PP
\fI\s-1CODE REFS\s0\fR
.IX Subsection "CODE REFS"
.PP
When a filter is passed in the form of a \s-1CODE\s0 ref, each such item is executed in
its own subprocess in the following way.
.PP
.Vb 1
\&    exit $filter\->();
.Ve
.SS "\s-1BEHAVIOR\s0"
.IX Subsection "BEHAVIOR"
If fileglobs or numeric file descriptors are passed in any of the three
positional parameters, then they will be duplicated onto the file handles
allocated as a result of the process pipelining.  Otherwise, simple scalar
assignment will be performed.
.PP
Like IPC::Open3, \f(CW\*(C`pipeline()\*(C'\fR returns immediately after spawning the process
chain, though differing slightly in that the IDs of each process is returned
in order of specification in a list when called in array context.  When called
in scalar context, an \s-1ARRAY\s0 reference of the process IDs will be returned.
.PP
Also like IPC::Open3, one may use \f(CW\*(C`select()\*(C'\fR to multiplex reading and writing
to each of the handles returned by \f(CW\*(C`pipeline()\*(C'\fR, preferably with non-buffered
\&\fIsysread()\fR and \fIsyswrite()\fR calls.  Using
this to handle reading standard output and error from the children is ideal, as
blocking and buffering considerations are alleviated.
.SS "\s-1CAVEATS\s0"
.IX Subsection "CAVEATS"
If any child process dies prematurely, or any of the piped file handles are
closed for any reason, the calling process inherits the kernel behavior of
receiving a \f(CW\*(C`SIGPIPE\*(C'\fR, which requires the installation of a signal handler for
appropriate recovery.
.PP
Unlike IPC::Open3, \fBIPC::Pipeline\fR will \s-1NOT\s0 redirect child process stderr to
stdout if no file handle for stderr is specified.  As of version 0.6, the caller
will always need to handle standard error, to prevent any children from
blocking; it would make little sense to pass one process' standard error as an
input to the next process.
.SH "EXAMPLE ONE \- OUTPUT ONLY"
.IX Header "EXAMPLE ONE - OUTPUT ONLY"
The following example implements a quick and dirty, but relatively sane tar and
gzip solution.  For proper error handling from any of the children, use \f(CW\*(C`select()\*(C'\fR
to multiplex the output and error streams.
.PP
.Vb 1
\&    use IPC::Pipeline;
\&
\&    my @paths = qw(/some /random /locations);
\&
\&    open(my $err, \*(Aq<\*(Aq, \*(Aq/dev/null\*(Aq);
\&
\&    my @pids = pipeline(my ($in, $out), $err,
\&        [qw(tar pcf \-), @paths],
\&        [\*(Aqgzip\*(Aq]
\&    );
\&
\&    open(my $fh, \*(Aq>\*(Aq, \*(Aqfile.tar.gz\*(Aq);
\&    close $in;
\&
\&    while (my $len = sysread($out, my $buf, 512)) {
\&        syswrite($fh, $buf, $len);
\&    }
\&
\&    close $fh;
\&    close $out;
\&
\&    #
\&    # We may need to wait for the children to die in some extraordinary
\&    # circumstances.
\&    #
\&    foreach my $pid (@pids) {
\&        waitpid($pid, 1);
\&    }
.Ve
.SH "EXAMPLE TWO \- INPUT AND OUTPUT"
.IX Header "EXAMPLE TWO - INPUT AND OUTPUT"
The following solution implements a true I/O stream filter as provided by any
Unix-style shell.
.PP
.Vb 1
\&    use IPC::Pipeline;
\&
\&    open(my $err, \*(Aq<\*(Aq, \*(Aq/dev/null\*(Aq);
\&
\&    my @pids = pipeline(my ($in, $out), $err,
\&        [qw(tr A\-Ma\-mN\-Zn\-z N\-Zn\-zA\-Ma\-m)],
\&        [qw(cut \-d), \*(Aq:\*(Aq, qw(\-f 2)]
\&    );
\&
\&    my @records = qw(
\&        foo:bar:baz
\&        eins:zwei:drei
\&        cats:dogs:rabbits
\&    );
\&
\&    foreach my $record (@records) {
\&        print $in $record ."\en";
\&    }
\&
\&    close $in;
\&
\&    while (my $len = sysread($out, my $buf, 512)) {
\&        syswrite(STDOUT, $buf, $len);
\&    }
\&
\&    close $out;
\&
\&    foreach my $pid (@pids) {
\&        waitpid($pid, 1);
\&    }
.Ve
.SH "EXAMPLE THREE \- MIXING COMMANDS AND CODEREFS"
.IX Header "EXAMPLE THREE - MIXING COMMANDS AND CODEREFS"
The following solution demonstrates the ability of IPC::Pipeline to execute \s-1CODE\s0
references in the midst of a pipeline.
.PP
.Vb 1
\&    use IPC::Pipeline;
\&
\&    open(my $err, \*(Aq<\*(Aq, \*(Aq/dev/null\*(Aq);
\&
\&    my @pids = pipeline(my ($in, $out), $err,
\&        sub { print \*(Aqcats\*(Aq; return 0 },
\&        [qw(tr acst lbhe)]
\&    );
\&
\&    close $in;
\&
\&    while (my $line = readline($out)) {
\&        chomp $line;
\&        print "Got \*(Aq$line\*(Aq\en";
\&    }
\&
\&    close $out;
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "IPC::Open3" 4
.IX Item "IPC::Open3"
.PD 0
.IP "IPC::Run, for a Swiss Army knife of Unix I/O gizmos" 4
.IX Item "IPC::Run, for a Swiss Army knife of Unix I/O gizmos"
.PD
It should be mentioned that mst's IO::Pipeline has very little in common with
\&\fBIPC::Pipeline\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Written by Xan Tronix <xan@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2014, cPanel, Inc.
All rights reserved.
http://cpanel.net/
.PP
This is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.  See the \s-1LICENSE\s0 file for further details.