.\" Automatically generated by Pod::Man 2.28 (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 "IO::Async::Process 3pm"
.TH IO::Async::Process 3pm "2014-10-21" "perl v5.20.1" "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"
"IO::Async::Process" \- start and manage a child process
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use IO::Async::Process;
\&
\& use IO::Async::Loop;
\& my $loop = IO::Async::Loop\->new;
\&
\& my $process = IO::Async::Process\->new(
\&    command => [ "tr", "a\-z", "n\-za\-m" ],
\&    stdin => {
\&       from => "hello world\en",
\&    },
\&    stdout => {
\&       on_read => sub {
\&          my ( $stream, $buffref ) = @_;
\&          while( $$buffref =~ s/^(.*)\en// ) {
\&             print "Rot13 of \*(Aqhello world\*(Aq is \*(Aq$1\*(Aq\en";
\&          }
\&          
\&          return 0;
\&       },
\&    },
\&    
\&    on_finish => sub {
\&       $loop\->stop;
\&    },
\& );
\&
\& $loop\->add( $process );
\&
\& $loop\->run;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This subclass of IO::Async::Notifier starts a child process, and invokes a
callback when it exits. The child process can either execute a given block of
code (via \f(CWfork(2)\fR), or a command.
.SH "EVENTS"
.IX Header "EVENTS"
The following events are invoked, either using subclass methods or \s-1CODE\s0
references in parameters:
.ie n .SS "on_finish $exitcode"
.el .SS "on_finish \f(CW$exitcode\fP"
.IX Subsection "on_finish $exitcode"
Invoked after the process has exited by normal means (i.e. an \f(CWexit(2)\fR
syscall from a process, or \f(CW\*(C`return\*(C'\fRing from the code block), and has closed
all its file descriptors.
.ie n .SS "on_exception $exception, $errno, $exitcode"
.el .SS "on_exception \f(CW$exception\fP, \f(CW$errno\fP, \f(CW$exitcode\fP"
.IX Subsection "on_exception $exception, $errno, $exitcode"
Invoked when the process exits by an exception from \f(CW\*(C`code\*(C'\fR, or by failing to
\&\f(CWexec(2)\fR the given command. \f(CW$errno\fR will be a dualvar, containing both
number and string values.
.PP
Note that this has a different name and a different argument order from
\&\f(CW\*(C`Loop\->open_child\*(C'\fR's \f(CW\*(C`on_error\*(C'\fR.
.PP
If this is not provided and the process exits with an exception, then
\&\f(CW\*(C`on_finish\*(C'\fR is invoked instead, being passed just the exit code.
.PP
Since this is just the results of the underlying \f(CW\*(C`$loop\->spawn_child\*(C'\fR
\&\f(CW\*(C`on_exit\*(C'\fR handler in a different order it is possible that the \f(CW$exception\fR
field will be an empty string. It will however always be defined. This can be
used to distinguish the two cases:
.PP
.Vb 2
\& on_exception => sub {
\&    my ( $self, $exception, $errno, $exitcode ) = @_;
\&
\&    if( length $exception ) {
\&       print STDERR "The process died with the exception $exception " .
\&          "(errno was $errno)\en";
\&    }
\&    elsif( ( my $status = W_EXITSTATUS($exitcode) ) == 255 ) {
\&       print STDERR "The process failed to exec() \- $errno\en";
\&    }
\&    else {
\&       print STDERR "The process exited with exit status $status\en";
\&    }
\& }
.Ve
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.ie n .SS "$process = IO::Async::Process\->new( %args )"
.el .SS "\f(CW$process\fP = IO::Async::Process\->new( \f(CW%args\fP )"
.IX Subsection "$process = IO::Async::Process->new( %args )"
Constructs a new \f(CW\*(C`IO::Async::Process\*(C'\fR object and returns it.
.PP
Once constructed, the \f(CW\*(C`Process\*(C'\fR will need to be added to the \f(CW\*(C`Loop\*(C'\fR before
the child process is started.
.SH "PARAMETERS"
.IX Header "PARAMETERS"
The following named parameters may be passed to \f(CW\*(C`new\*(C'\fR or \f(CW\*(C`configure\*(C'\fR:
.SS "on_finish => \s-1CODE\s0"
.IX Subsection "on_finish => CODE"
.SS "on_exception => \s-1CODE\s0"
.IX Subsection "on_exception => CODE"
\&\s-1CODE\s0 reference for the event handlers.
.PP
Once the \f(CW\*(C`on_finish\*(C'\fR continuation has been invoked, the \f(CW\*(C`IO::Async::Process\*(C'\fR
object is removed from the containing \f(CW\*(C`IO::Async::Loop\*(C'\fR object.
.PP
The following parameters may be passed to \f(CW\*(C`new\*(C'\fR, or to \f(CW\*(C`configure\*(C'\fR before
the process has been started (i.e. before it has been added to the \f(CW\*(C`Loop\*(C'\fR).
Once the process is running these cannot be changed.
.SS "command => \s-1ARRAY\s0 or \s-1STRING\s0"
.IX Subsection "command => ARRAY or STRING"
Either a reference to an array containing the command and its arguments, or a
plain string containing the command. This value is passed into perl's
\&\f(CWexec(2)\fR function.
.SS "code => \s-1CODE\s0"
.IX Subsection "code => CODE"
A block of code to execute in the child process. It will be called in scalar
context inside an \f(CW\*(C`eval\*(C'\fR block.
.SS "setup => \s-1ARRAY\s0"
.IX Subsection "setup => ARRAY"
Optional reference to an array to pass to the underlying \f(CW\*(C`Loop\*(C'\fR
\&\f(CW\*(C`spawn_child\*(C'\fR method.
.SS "fd\fIn\fP => \s-1HASH\s0"
.IX Subsection "fdn => HASH"
A hash describing how to set up file descriptor \fIn\fR. The hash may contain the
following keys:
.IP "via => \s-1STRING\s0" 4
.IX Item "via => STRING"
Configures how this file descriptor will be configured for the child process.
Must be given one of the following mode names:
.RS 4
.IP "pipe_read" 4
.IX Item "pipe_read"
The child will be given the writing end of a \f(CWpipe(2)\fR; the parent may read
from the other.
.IP "pipe_write" 4
.IX Item "pipe_write"
The child will be given the reading end of a \f(CWpipe(2)\fR; the parent may write
to the other. Since an \s-1EOF\s0 condition of this kind of handle cannot reliably be
detected, \f(CW\*(C`on_finish\*(C'\fR will not wait for this type of pipe to be closed.
.IP "pipe_rdwr" 4
.IX Item "pipe_rdwr"
Only valid on the \f(CW\*(C`stdio\*(C'\fR filehandle. The child will be given the reading end
of one \f(CWpipe(2)\fR on \s-1STDIN\s0 and the writing end of another on \s-1STDOUT. A\s0 single
Stream object will be created in the parent configured for both filehandles.
.IP "socketpair" 4
.IX Item "socketpair"
The child will be given one end of a \f(CWsocketpair(2)\fR; the parent will be
given the other. The family of this socket may be given by the extra key
called \f(CW\*(C`family\*(C'\fR; defaulting to \f(CW\*(C`unix\*(C'\fR. The socktype of this socket may be
given by the extra key called \f(CW\*(C`socktype\*(C'\fR; defaulting to \f(CW\*(C`stream\*(C'\fR. If the
type is not \f(CW\*(C`SOCK_STREAM\*(C'\fR then a IO::Async::Socket object will be
constructed for the parent side of the handle, rather than
\&\f(CW\*(C`IO::Async::Stream\*(C'\fR.
.RE
.RS 4
.Sp
Once the filehandle is set up, the \f(CW\*(C`fd\*(C'\fR method (or its shortcuts of \f(CW\*(C`stdin\*(C'\fR,
\&\f(CW\*(C`stdout\*(C'\fR or \f(CW\*(C`stderr\*(C'\fR) may be used to access the
\&\f(CW\*(C`IO::Async::Handle\*(C'\fR\-subclassed object wrapped around it.
.Sp
The value of this argument is implied by any of the following alternatives.
.RE
.IP "on_read => \s-1CODE\s0" 4
.IX Item "on_read => CODE"
The child will be given the writing end of a pipe. The reading end will be
wrapped by an \f(CW\*(C`IO::Async::Stream\*(C'\fR using this \f(CW\*(C`on_read\*(C'\fR callback function.
.IP "into => \s-1SCALAR\s0" 4
.IX Item "into => SCALAR"
The child will be given the writing end of a pipe. The referenced scalar will
be filled by data read from the child process. This data may not be available
until the pipe has been closed by the child.
.IP "from => \s-1STRING\s0" 4
.IX Item "from => STRING"
The child will be given the reading end of a pipe. The string given by the
\&\f(CW\*(C`from\*(C'\fR parameter will be written to the child. When all of the data has been
written the pipe will be closed.
.SS "stdin => ..."
.IX Subsection "stdin => ..."
.SS "stdout => ..."
.IX Subsection "stdout => ..."
.SS "stderr => ..."
.IX Subsection "stderr => ..."
Shortcuts for \f(CW\*(C`fd0\*(C'\fR, \f(CW\*(C`fd1\*(C'\fR and \f(CW\*(C`fd2\*(C'\fR respectively.
.SS "stdio => ..."
.IX Subsection "stdio => ..."
Special filehandle to affect \s-1STDIN\s0 and \s-1STDOUT\s0 at the same time. This
filehandle supports being configured for both reading and writing at the same
time.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "$pid = $process\->pid"
.el .SS "\f(CW$pid\fP = \f(CW$process\fP\->pid"
.IX Subsection "$pid = $process->pid"
Returns the process \s-1ID\s0 of the process, if it has been started, or \f(CW\*(C`undef\*(C'\fR if
not. Its value is preserved after the process exits, so it may be inspected
during the \f(CW\*(C`on_finish\*(C'\fR or \f(CW\*(C`on_exception\*(C'\fR events.
.ie n .SS "$process\->kill( $signal )"
.el .SS "\f(CW$process\fP\->kill( \f(CW$signal\fP )"
.IX Subsection "$process->kill( $signal )"
Sends a signal to the process
.ie n .SS "$running = $process\->is_running"
.el .SS "\f(CW$running\fP = \f(CW$process\fP\->is_running"
.IX Subsection "$running = $process->is_running"
Returns true if the Process has been started, and has not yet finished.
.ie n .SS "$exited = $process\->is_exited"
.el .SS "\f(CW$exited\fP = \f(CW$process\fP\->is_exited"
.IX Subsection "$exited = $process->is_exited"
Returns true if the Process has finished running, and finished due to normal
\&\f(CWexit(2)\fR.
.ie n .SS "$status = $process\->exitstatus"
.el .SS "\f(CW$status\fP = \f(CW$process\fP\->exitstatus"
.IX Subsection "$status = $process->exitstatus"
If the process exited due to normal \f(CWexit(2)\fR, returns the value that was
passed to \f(CWexit(2)\fR. Otherwise, returns \f(CW\*(C`undef\*(C'\fR.
.ie n .SS "$exception = $process\->exception"
.el .SS "\f(CW$exception\fP = \f(CW$process\fP\->exception"
.IX Subsection "$exception = $process->exception"
If the process exited due to an exception, returns the exception that was
thrown. Otherwise, returns \f(CW\*(C`undef\*(C'\fR.
.ie n .SS "$errno = $process\->errno"
.el .SS "\f(CW$errno\fP = \f(CW$process\fP\->errno"
.IX Subsection "$errno = $process->errno"
If the process exited due to an exception, returns the numerical value of
\&\f(CW$!\fR at the time the exception was thrown. Otherwise, returns \f(CW\*(C`undef\*(C'\fR.
.ie n .SS "$errstr = $process\->errstr"
.el .SS "\f(CW$errstr\fP = \f(CW$process\fP\->errstr"
.IX Subsection "$errstr = $process->errstr"
If the process exited due to an exception, returns the string value of
\&\f(CW$!\fR at the time the exception was thrown. Otherwise, returns \f(CW\*(C`undef\*(C'\fR.
.ie n .SS "$stream = $process\->fd( $fd )"
.el .SS "\f(CW$stream\fP = \f(CW$process\fP\->fd( \f(CW$fd\fP )"
.IX Subsection "$stream = $process->fd( $fd )"
Returns the IO::Async::Stream or IO::Async::Socket associated with the
given \s-1FD\s0 number. This must have been set up by a \f(CW\*(C`configure\*(C'\fR argument prior
to adding the \f(CW\*(C`Process\*(C'\fR object to the \f(CW\*(C`Loop\*(C'\fR.
.PP
The returned object have its read or write handle set to the other end of a
pipe or socket connected to that \s-1FD\s0 number in the child process. Typically,
this will be used to call the \f(CW\*(C`write\*(C'\fR method on, to write more data into the
child, or to set an \f(CW\*(C`on_read\*(C'\fR handler to read data out of the child.
.PP
The \f(CW\*(C`on_closed\*(C'\fR event for these streams must not be changed, or it will break
the close detection used by the \f(CW\*(C`Process\*(C'\fR object and the \f(CW\*(C`on_finish\*(C'\fR event
will not be invoked.
.ie n .SS "$stream = $process\->stdin"
.el .SS "\f(CW$stream\fP = \f(CW$process\fP\->stdin"
.IX Subsection "$stream = $process->stdin"
.ie n .SS "$stream = $process\->stdout"
.el .SS "\f(CW$stream\fP = \f(CW$process\fP\->stdout"
.IX Subsection "$stream = $process->stdout"
.ie n .SS "$stream = $process\->stderr"
.el .SS "\f(CW$stream\fP = \f(CW$process\fP\->stderr"
.IX Subsection "$stream = $process->stderr"
.ie n .SS "$stream = $process\->stdio"
.el .SS "\f(CW$stream\fP = \f(CW$process\fP\->stdio"
.IX Subsection "$stream = $process->stdio"
Shortcuts for calling \f(CW\*(C`fd\*(C'\fR with 0, 1, 2 or \f(CW\*(C`io\*(C'\fR respectively, to obtain the
IO::Async::Stream representing the standard input, output, error, or
combined input/output streams of the child process.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Capturing the \s-1STDOUT\s0 stream of a process"
.IX Subsection "Capturing the STDOUT stream of a process"
By configuring the \f(CW\*(C`stdout\*(C'\fR filehandle of the process using the \f(CW\*(C`into\*(C'\fR key,
data written by the process can be captured.
.PP
.Vb 9
\& my $stdout;
\& my $process = IO::Async::Process\->new(
\&    command => [ "writing\-program", "arguments" ],
\&    stdout => { into => \e$stdout },
\&    on_finish => sub {
\&       print "The process has finished, and wrote:\en";
\&       print $stdout;
\&    }
\& );
\&
\& $loop\->add( $process );
.Ve
.PP
Note that until \f(CW\*(C`on_finish\*(C'\fR is invoked, no guarantees are made about how much
of the data actually written by the process is yet in the \f(CW$stdout\fR scalar.
.PP
See also the \f(CW\*(C`run_child\*(C'\fR method of IO::Async::Loop.
.PP
To handle data more interactively as it arrives, the \f(CW\*(C`on_read\*(C'\fR key can
instead be used, to provide a callback function to invoke whenever more data
is available from the process.
.PP
.Vb 8
\& my $process = IO::Async::Process\->new(
\&    command => [ "writing\-program", "arguments" ],
\&    stdout => {
\&       on_read => sub {
\&          my ( $stream, $buffref ) = @_;
\&          while( $$buffref =~ s/^(.*)\en// ) {
\&             print "The process wrote a line: $1\en";
\&          }
\&
\&          return 0;
\&       },
\&    },
\&    on_finish => sub {
\&       print "The process has finished\en";
\&    }
\& );
\&
\& $loop\->add( $process );
.Ve
.PP
If the code to handle data read from the process isn't available yet when
the object is constructed, it can be supplied later by using the \f(CW\*(C`configure\*(C'\fR
method on the \f(CW\*(C`stdout\*(C'\fR filestream at some point before it gets added to the
Loop. In this case, \f(CW\*(C`stdin\*(C'\fR should be configured using \f(CW\*(C`pipe_read\*(C'\fR in the
\&\f(CW\*(C`via\*(C'\fR key.
.PP
.Vb 7
\& my $process = IO::Async::Process\->new(
\&    command => [ "writing\-program", "arguments" ],
\&    stdout => { via => "pipe_read" },
\&    on_finish => sub {
\&       print "The process has finished\en";
\&    }
\& );
\&
\& $process\->stdout\->configure(
\&    on_read => sub {
\&       my ( $stream, $buffref ) = @_;
\&       while( $$buffref =~ s/^(.*)\en// ) {
\&          print "The process wrote a line: $1\en";
\&       }
\&
\&       return 0;
\&    },
\& );
\&
\& $loop\->add( $process );
.Ve
.SS "Sending data to \s-1STDIN\s0 of a process"
.IX Subsection "Sending data to STDIN of a process"
By configuring the \f(CW\*(C`stdin\*(C'\fR filehandle of the process using the \f(CW\*(C`from\*(C'\fR key,
data can be written into the \f(CW\*(C`STDIN\*(C'\fR stream of the process.
.PP
.Vb 7
\& my $process = IO::Async::Process\->new(
\&    command => [ "reading\-program", "arguments" ],
\&    stdin => { from => "Here is the data to send\en" },
\&    on_finish => sub { 
\&       print "The process has finished\en";
\&    }
\& );
\&
\& $loop\->add( $process );
.Ve
.PP
The data in this scalar will be written until it is all consumed, then the
handle will be closed. This may be useful if the program waits for \s-1EOF\s0 on
\&\f(CW\*(C`STDIN\*(C'\fR before it exits.
.PP
To have the ability to write more data into the process once it has started.
the \f(CW\*(C`write\*(C'\fR method on the \f(CW\*(C`stdin\*(C'\fR stream can be used, when it is configured
using the \f(CW\*(C`pipe_write\*(C'\fR value for \f(CW\*(C`via\*(C'\fR:
.PP
.Vb 7
\& my $process = IO::Async::Process\->new(
\&    command => [ "reading\-program", "arguments" ],
\&    stdin => { via => "pipe_write" },
\&    on_finish => sub { 
\&       print "The process has finished\en";
\&    }
\& );
\&
\& $loop\->add( $process );
\&
\& $process\->stdin\->write( "Here is some more data\en" );
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>