.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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 >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
.\"
.\" 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 "Lintian::Command 3"
.TH Lintian::Command 3 "2020-04-23" "Lintian v2.66.0~bpo10+1" "Debian Package Checker"
.\" 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"
Lintian::Command \- Utilities to execute other commands from lintian code
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Lintian::Command qw(spawn);
\&
\&    # simplest possible call
\&    my $success = spawn({}, [\*(Aqcommand\*(Aq]);
\&
\&    # catch output
\&    my $opts = {};
\&    $success = spawn($opts, [\*(Aqcommand\*(Aq]);
\&    if ($success) {
\&        print "STDOUT: $opts\->{out}\en";
\&        print "STDERR: $opts\->{err}\en";
\&    }
\&
\&    # from file to file
\&    $opts = { in => \*(Aqinfile.txt\*(Aq, out => \*(Aqoutfile.txt\*(Aq };
\&    $success = spawn($opts, [\*(Aqcommand\*(Aq]);
\&
\&    # piping
\&    $success = spawn({}, [\*(Aqcommand\*(Aq], "|", [\*(Aqothercommand\*(Aq]);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Lintian::Command is a thin wrapper around IPC::Run, that catches exception
and implements a useful default behaviour for input and output redirection.
.PP
Lintian::Command provides a function \fBspawn()\fR which is a wrapper
around \fBIPC::Run::run()\fR resp. \fBIPC::Run::start()\fR (depending on whether a
pipe is requested).  To wait for finished child processes, it also
provides the \fBreap()\fR function as a wrapper around \fBIPC::Run::finish()\fR.
.ie n .SS """spawn($opts, @cmds)"""
.el .SS "\f(CWspawn($opts, @cmds)\fP"
.IX Subsection "spawn($opts, @cmds)"
The \f(CW@cmds\fR array is given to \fBIPC::Run::run()\fR (or ::\fBstart()\fR) unaltered, but
should only be used for commands and piping symbols (i.e. all of the elements
should be either an array reference, a code reference, '|', or '&').  I/O
redirection is handled via the \f(CW$opts\fR hash reference. If you need more fine
grained control than that, you should just use IPC::Run directly.
.PP
\&\f(CW$opts\fR is a hash reference which can be used to set options and to retrieve
the status and output of the command executed.
.PP
The following hash keys can be set to alter the behaviour of \fBspawn()\fR:
.IP "in" 4
.IX Item "in"
\&\s-1STDIN\s0 for the first forked child.  Defaults to \f(CW\*(C`\eundef\*(C'\fR.
.Sp
\&\s-1CAVEAT:\s0 Due to #301774, passing a \s-1SCALAR\s0 ref as \s-1STDIN\s0 for the child
leaks memory.  The leak is plugged for the \f(CW\*(C`\eundef\*(C'\fR case in spawn,
but other scalar refs may still be leaked.
.IP "pipe_in" 4
.IX Item "pipe_in"
Use a pipe for \s-1STDIN\s0 and start the process in the background.
You will need to close the pipe after use and call \f(CW$opts\fR\->{harness}\->finish
in order for the started process to end properly.
.IP "out" 4
.IX Item "out"
\&\s-1STDOUT\s0 of the last forked child.  Will be set to a newly created
scalar reference by default which can be used to retrieve the output
after the call.
.Sp
Can be '&N' (e.g. &2) to redirect it to (numeric) file descriptor.
.IP "out_append" 4
.IX Item "out_append"
\&\s-1STDOUT\s0 of all forked children, cannot be used with out and should only be
used with files.  Unlike out, this appends the output to the file
instead of truncating the file.
.IP "pipe_out" 4
.IX Item "pipe_out"
Use a pipe for \s-1STDOUT\s0 and start the process in the background.
You will need to call \f(CW$opts\fR\->{harness}\->finish in order for the started
process to end properly.
.IP "err" 4
.IX Item "err"
\&\s-1STDERR\s0 of all forked children.  Defaults to \s-1STDERR\s0 of the parent.
.Sp
Can be '&N' (e.g. &1) to redirect it to (numeric) file descriptor.
.IP "err_append" 4
.IX Item "err_append"
\&\s-1STDERR\s0 of all forked children, cannot be used with err and should only be
used with files.  Unlike err, this appends the output to the file
instead of truncating the file.
.IP "pipe_err" 4
.IX Item "pipe_err"
Use a pipe for \s-1STDERR\s0 and start the process in the background.
You will need to call \f(CW$opts\fR\->{harness}\->finish in order for the started
process to end properly.
.IP "fail" 4
.IX Item "fail"
Configures the behaviour in case of errors. The default is 'exception',
which will cause \fBspawn()\fR to die in case of exceptions thrown by IPC::Run.
If set to 'error' instead, it will also die if the command exits
with a non-zero error code.  If exceptions should be handled by the caller,
setting it to 'never' will cause it to store the exception in the
\&\f(CW\*(C`exception\*(C'\fR key instead.
.IP "child_before_exec" 4
.IX Item "child_before_exec"
Run the given subroutine in each of the children before they run
\&\*(L"exec\*(R".
.Sp
This is passed to \*(L"harness\*(R" in IPC::Run as the \fIinit\fR keyword.
.PP
The following additional keys will be set during the execution of \fBspawn()\fR:
.IP "harness" 4
.IX Item "harness"
Will contain the IPC::Run object used for the call which can be used to
query the exit values of the forked programs (E.g. with \fBresults()\fR and
\&\fBfull_results()\fR) and to wait for processes started in the background.
.IP "exception" 4
.IX Item "exception"
If an exception is raised during the execution of the commands,
and if \f(CW\*(C`fail\*(C'\fR is set to 'never', the exception will be caught and
stored under this key.
.IP "success" 4
.IX Item "success"
Will contain the return value of \fBspawn()\fR.
.ie n .SS """reap($opts[, $opts[,...]])"""
.el .SS "\f(CWreap($opts[, $opts[,...]])\fP"
.IX Subsection "reap($opts[, $opts[,...]])"
If you used one of the \f(CW\*(C`pipe_*\*(C'\fR options to \fBspawn()\fR or used the shell-style \*(L"&\*(R"
operator to send the process to the background, you will need to wait for your
child processes to finish.  For this you can use the \fBreap()\fR function,
which you can call with the \f(CW$opts\fR hash reference you gave to \fBspawn()\fR and which
will do the right thing. Multiple \f(CW$opts\fR can be passed.
.PP
Note however that this function will not close any of the pipes for you, so
you probably want to do that first before calling this function.
.PP
The following keys of the \f(CW$opts\fR hash have roughly the same function as
for \fBspawn()\fR:
.IP "harness" 4
.IX Item "harness"
.PD 0
.IP "fail" 4
.IX Item "fail"
.IP "success" 4
.IX Item "success"
.IP "exception" 4
.IX Item "exception"
.PD
.PP
All other keys are probably just ignored.
.ie n .SS """kill($opts[, $opts[, ...]])"""
.el .SS "\f(CWkill($opts[, $opts[, ...]])\fP"
.IX Subsection "kill($opts[, $opts[, ...]])"
This is a simple wrapper around the kill_kill function. It doesn't allow
any customisation, but takes an \f(CW$opts\fR hash ref and SIGKILLs the process
two seconds after \s-1SIGTERM\s0 is sent. If multiple hash refs are passed it
executes kill_kill on each of them. The return status is the ORed value of
all the executions of kill_kill.
.ie n .SS """done($opts)"""
.el .SS "\f(CWdone($opts)\fP"
.IX Subsection "done($opts)"
Check if a process and its children are done. This is useful when one wants to
know whether \fBreap()\fR can be called without blocking waiting for the process.
It takes a single hash reference as returned by spawn.
.ie n .SS """safe_qx([$opts,] @cmds)"""
.el .SS "\f(CWsafe_qx([$opts,] @cmds)\fP"
.IX Subsection "safe_qx([$opts,] @cmds)"
Variant of spawn that emulates the \f(CW\*(C`qx()\*(C'\fR operator by returning the
captured output.
.PP
It takes the same arguments as \f(CW\*(C`spawn\*(C'\fR and they have the same
basic semantics with the following exceptions:
.ie n .IP "The initial $opts is optional." 4
.el .IP "The initial \f(CW$opts\fR is optional." 4
.IX Item "The initial $opts is optional."
.PD 0
.IP "If only a single command is to be run, the surrounding list reference can be omitted (see the examples below)." 4
.IX Item "If only a single command is to be run, the surrounding list reference can be omitted (see the examples below)."
.PD
.PP
If \f(CW$opts\fR is given, caller must ensure that the output is captured as a
scalar reference in \f(CW\*(C`$opts\-\*(C'\fR{out}> (possibly by omitting the \*(L"out\*(R"
and \*(L"out_append\*(R" keys).
.PP
Furthermore, the commands should not be backgrounded, so they cannot
use '&' nor (e.g. \f(CW\*(C`$opts\-\*(C'\fR{pipe_in}>).
.PP
If needed \f(CW$?\fR will be set after the call like for \f(CW\*(C`qx()\*(C'\fR.
.PP
Examples:
.PP
.Vb 4
\&  # Capture the output of a simple command
\&  # \- Both are eqv.
\&  safe_qx(\*(Aqgrep\*(Aq, \*(Aqsome\-pattern\*(Aq, \*(Aqpath/to/file\*(Aq);
\&  safe_qx([\*(Aqgrep\*(Aq, \*(Aqsome\-pattern\*(Aq, \*(Aqpath/to/file\*(Aq]);
\&
\&  # Capture the output of some pipeline
\&  safe_qx([\*(Aqgrep\*(Aq, \*(Aqsome\-pattern\*(Aq, \*(Aqpath/to/file\*(Aq], \*(Aq|\*(Aq,
\&          [\*(Aqhead\*(Aq, \*(Aq\-n1\*(Aq])
\&
\&  # Call nproc and capture stdout and stderr interleaved
\&  safe_qx({ \*(Aqerr\*(Aq => \*(Aq&1\*(Aq}, \*(Aqnproc\*(Aq)
\&
\&  #  WRONG: Runs grep with 5 arguments including a literal "|" and
\&  # "\-n1", which will generally fail with bad arguments.
\&  safe_qx(\*(Aqgrep\*(Aq, \*(Aqsome\-pattern\*(Aq, \*(Aqpath/to/file\*(Aq, \*(Aq|\*(Aq,
\&          \*(Aqhead\*(Aq, \*(Aq\-n1\*(Aq)
.Ve
.PP
Possible known issue: It might not possible to discard stdout and
capture stderr instead.
.SH "EXPORTS"
.IX Header "EXPORTS"
Lintian::Command exports nothing by default, but you can export the
\&\fBspawn()\fR and \fBreap()\fR functions.
.SH "AUTHOR"
.IX Header "AUTHOR"
Originally written by Frank Lichtenheld <djpig@debian.org> for Lintian.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBlintian\fR\|(1), IPC::Run