Lintian::Command(3) | Debian Package Checker | Lintian::Command(3) |
Lintian::Command - Utilities to execute other commands from lintian code
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']);
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().
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():
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.
Can be '&N' (e.g. &2) to redirect it to (numeric) file descriptor.
Can be '&N' (e.g. &1) to redirect it to (numeric) file descriptor.
This is passed to "harness" in IPC::Run as the init keyword.
The following additional keys will be set during the execution of spawn():
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():
All other keys are probably just ignored.
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.
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.
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:
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.
Lintian::Command exports nothing by default, but you can export the spawn() and reap() functions.
Originally written by Frank Lichtenheld <djpig@debian.org> for Lintian.
lintian(1), IPC::Run
2019-05-26 | Lintian v2.15.0 |