NAME

       Lintian::Command - Utilities to execute other commands from lintian code

SYNOPSIS

           use Lintian::Command qw(spawn);

           # simplest possible call
           my $success = spawn({}, ['command']);

           # catch output
           my $opts = {};
           $success = spawn($opts, ['command']);
           if ($success) {
               print "STDOUT: $opts->{out}\n";
               print "STDERR: $opts->{err}\n";
           }

           # from file to file
           $opts = { in => 'infile.txt', out => 'outfile.txt' };
           $success = spawn($opts, ['command']);

           # piping
           $success = spawn({}, ['command'], "|", ['othercommand']);

DESCRIPTION

       Lintian::Command is a thin wrapper around IPC::Run, that catches exception and implements
       a useful default behaviour for input and output redirection.

       Lintian::Command provides a function spawn() which is a wrapper around IPC::Run::run()
       resp. IPC::Run::start() (depending on whether a pipe is requested).  To wait for finished
       child processes, it also provides the reap() function as a wrapper around
       IPC::Run::finish().

   "spawn($opts, @cmds)"
       The @cmds array is given to IPC::Run::run() (or ::start()) 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 $opts hash
       reference. If you need more fine grained control than that, you should just use IPC::Run
       directly.

       $opts is a hash reference which can be used to set options and to retrieve the status and
       output of the command executed.

       The following hash keys can be set to alter the behaviour of spawn():

       in  STDIN for the first forked child.  Defaults to "\undef".

           CAVEAT: Due to #301774, passing a SCALAR ref as STDIN for the child leaks memory.  The
           leak is plugged for the "\undef" case in spawn, but other scalar refs may still be
           leaked.

       pipe_in
           Use a pipe for STDIN and start the process in the background.  You will need to close
           the pipe after use and call $opts->{harness}->finish in order for the started process
           to end properly.

       out STDOUT 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.

           Can be '&N' (e.g. &2) to redirect it to (numeric) file descriptor.

       out_append
           STDOUT 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.

       pipe_out
           Use a pipe for STDOUT and start the process in the background.  You will need to call
           $opts->{harness}->finish in order for the started process to end properly.

       err STDERR of all forked children.  Defaults to STDERR of the parent.

           Can be '&N' (e.g. &1) to redirect it to (numeric) file descriptor.

       err_append
           STDERR 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.

       pipe_err
           Use a pipe for STDERR and start the process in the background.  You will need to call
           $opts->{harness}->finish in order for the started process to end properly.

       fail
           Configures the behaviour in case of errors. The default is 'exception', which will
           cause spawn() 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 "exception" key instead.

       child_before_exec
           Run the given subroutine in each of the children before they run "exec".

           This is passed to "harness" in IPC::Run as the init keyword.

       The following additional keys will be set during the execution of spawn():

       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 results() and full_results()) and to wait for
           processes started in the background.

       exception
           If an exception is raised during the execution of the commands, and if "fail" is set
           to 'never', the exception will be caught and stored under this key.

       success
           Will contain the return value of spawn().

   "reap($opts[, $opts[,...]])"
       If you used one of the "pipe_*" options to spawn() or used the shell-style "&" 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 reap() function, which you can call with the $opts hash
       reference you gave to spawn() and which will do the right thing. Multiple $opts can be
       passed.

       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.

       The following keys of the $opts hash have roughly the same function as for spawn():

       harness
       fail
       success
       exception

       All other keys are probably just ignored.

   "kill($opts[, $opts[, ...]])"
       This is a simple wrapper around the kill_kill function. It doesn't allow any
       customisation, but takes an $opts hash ref and SIGKILLs the process two seconds after
       SIGTERM 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.

   "done($opts)"
       Check if a process and its children are done. This is useful when one wants to know
       whether reap() can be called without blocking waiting for the process.  It takes a single
       hash reference as returned by spawn.

   "safe_qx([$opts,] @cmds)"
       Variant of spawn that emulates the "qx()" operator by returning the captured output.

       It takes the same arguments as "spawn" and they have the same basic semantics with the
       following exceptions:

       The initial $opts is optional.
       If only a single command is to be run, the surrounding list reference can be omitted (see
       the examples below).

       If $opts is given, caller must ensure that the output is captured as a scalar reference in
       "$opts-"{out}> (possibly by omitting the "out" and "out_append" keys).

       Furthermore, the commands should not be backgrounded, so they cannot use '&' nor (e.g.
       "$opts-"{pipe_in}>).

       If needed $? will be set after the call like for "qx()".

       Examples:

         # Capture the output of a simple command
         # - Both are eqv.
         safe_qx('grep', 'some-pattern', 'path/to/file');
         safe_qx(['grep', 'some-pattern', 'path/to/file']);

         # Capture the output of some pipeline
         safe_qx(['grep', 'some-pattern', 'path/to/file'], '|',
                 ['head', '-n1'])

         # Call nproc and capture stdout and stderr interleaved
         safe_qx({ 'err' => '&1'}, 'nproc')

         #  WRONG: Runs grep with 5 arguments including a literal "|" and
         # "-n1", which will generally fail with bad arguments.
         safe_qx('grep', 'some-pattern', 'path/to/file', '|',
                 'head', '-n1')

       Possible known issue: It might not possible to discard stdout and capture stderr instead.

EXPORTS

       Lintian::Command exports nothing by default, but you can export the spawn() and reap()
       functions.

AUTHOR

       Originally written by Frank Lichtenheld <djpig@debian.org> for Lintian.

SEE ALSO

       lintian(1), IPC::Run