/usr/share/doc/lintian/api.html/Lintian/Command.html is in lintian 2.5.43.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><title>Lintian::Command</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" title="blkbluw" type="text/css" href="../_blkbluw.css" media="all" >
<link rel="alternate stylesheet" title="blkmagw" type="text/css" href="../_blkmagw.css" media="all" >
<link rel="alternate stylesheet" title="blkcynw" type="text/css" href="../_blkcynw.css" media="all" >
<link rel="alternate stylesheet" title="whtprpk" type="text/css" href="../_whtprpk.css" media="all" >
<link rel="alternate stylesheet" title="whtnavk" type="text/css" href="../_whtnavk.css" media="all" >
<link rel="alternate stylesheet" title="grygrnk" type="text/css" href="../_grygrnk.css" media="all" >
<link rel="alternate stylesheet" title="whtgrng" type="text/css" href="../_whtgrng.css" media="all" >
<link rel="alternate stylesheet" title="blkgrng" type="text/css" href="../_blkgrng.css" media="all" >
<link rel="alternate stylesheet" title="grygrnw" type="text/css" href="../_grygrnw.css" media="all" >
<link rel="alternate stylesheet" title="blkbluw" type="text/css" href="../_blkbluw.css" media="all" >
<link rel="alternate stylesheet" title="whtpurk" type="text/css" href="../_whtpurk.css" media="all" >
<link rel="alternate stylesheet" title="whtgrng" type="text/css" href="../_whtgrng.css" media="all" >
<link rel="alternate stylesheet" title="grygrnw" type="text/css" href="../_grygrnw.css" media="all" >
<script type="text/javascript" src="../_podly.js"></script>
</head>
<body class='pod'>
<!-- start doc -->
<p class="backlinktop"><b><a name="___top" href="../index.html" accesskey="1" title="All Documents"><<</a></b></p>
<div class='indexgroup'>
<ul class='indexList indexList1'>
<li class='indexItem indexItem1'><a href='#NAME'>NAME</a>
<li class='indexItem indexItem1'><a href='#SYNOPSIS'>SYNOPSIS</a>
<li class='indexItem indexItem1'><a href='#DESCRIPTION'>DESCRIPTION</a>
<ul class='indexList indexList2'>
<li class='indexItem indexItem2'><a href='#spawn(%24opts%2C_%40cmds)'>spawn($opts, @cmds)</a>
<li class='indexItem indexItem2'><a href='#reap(%24opts%5B%2C_%24opts%5B%2C...%5D%5D)'>reap($opts[, $opts[,...]])</a>
<li class='indexItem indexItem2'><a href='#kill(%24opts%5B%2C_%24opts%5B%2C_...%5D%5D)'>kill($opts[, $opts[, ...]])</a>
<li class='indexItem indexItem2'><a href='#done(%24opts)'>done($opts)</a>
<li class='indexItem indexItem2'><a href='#safe_qx(%5B%24opts%2C%5D_%40cmds)'>safe_qx([$opts,] @cmds)</a>
</ul>
<li class='indexItem indexItem1'><a href='#EXPORTS'>EXPORTS</a>
<li class='indexItem indexItem1'><a href='#AUTHOR'>AUTHOR</a>
<li class='indexItem indexItem1'><a href='#SEE_ALSO'>SEE ALSO</a>
</ul>
</div>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="NAME"
>NAME</a></h1>
<p>Lintian::Command - Utilities to execute other commands from lintian code</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> 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']);</pre>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>Lintian::Command is a thin wrapper around IPC::Run, that catches exception and implements a useful default behaviour for input and output redirection.</p>
<p>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().</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="spawn($opts,_@cmds)"
><code>spawn($opts, @cmds)</code></a></h2>
<p>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.</p>
<p>$opts is a hash reference which can be used to set options and to retrieve the status and output of the command executed.</p>
<p>The following hash keys can be set to alter the behaviour of spawn():</p>
<dl>
<dt><a name="in"
>in</a></dt>
<dd>
<p>STDIN for the first forked child. Defaults to <code>\undef</code>.</p>
<p>CAVEAT: Due to #301774, passing a SCALAR ref as STDIN for the child leaks memory. The leak is plugged for the <code>\undef</code> case in spawn, but other scalar refs may still be leaked.</p>
<dt><a name="pipe_in"
>pipe_in</a></dt>
<dd>
<p>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.</p>
<dt><a name="out"
>out</a></dt>
<dd>
<p>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.</p>
<p>Can be '&N' (e.g. &2) to redirect it to (numeric) file descriptor.</p>
<dt><a name="out_append"
>out_append</a></dt>
<dd>
<p>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.</p>
<dt><a name="pipe_out"
>pipe_out</a></dt>
<dd>
<p>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.</p>
<dt><a name="err"
>err</a></dt>
<dd>
<p>STDERR of all forked children. Defaults to STDERR of the parent.</p>
<p>Can be '&N' (e.g. &1) to redirect it to (numeric) file descriptor.</p>
<dt><a name="err_append"
>err_append</a></dt>
<dd>
<p>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.</p>
<dt><a name="pipe_err"
>pipe_err</a></dt>
<dd>
<p>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.</p>
<dt><a name="fail"
>fail</a></dt>
<dd>
<p>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 <code>exception</code> key instead.</p>
<dt><a name="child_before_exec"
>child_before_exec</a></dt>
<dd>
<p>Run the given subroutine in each of the children before they run "exec".</p>
<p>This is passed to <a href="../IPC/Run.html#harness" class="podlinkpod"
>"harness" in IPC::Run</a> as the <i>init</i> keyword.</p>
</dd>
</dl>
<p>The following additional keys will be set during the execution of spawn():</p>
<dl>
<dt><a name="harness"
>harness</a></dt>
<dd>
<p>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.</p>
<dt><a name="exception"
>exception</a></dt>
<dd>
<p>If an exception is raised during the execution of the commands, and if <code>fail</code> is set to 'never', the exception will be caught and stored under this key.</p>
<dt><a name="success"
>success</a></dt>
<dd>
<p>Will contain the return value of spawn().</p>
</dd>
</dl>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="reap($opts[,_$opts[,...]])"
><code>reap($opts[, $opts[,...]])</code></a></h2>
<p>If you used one of the <code>pipe_*</code> 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.</p>
<p>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.</p>
<p>The following keys of the $opts hash have roughly the same function as for spawn():</p>
<dl>
<dt><a name="harness"
>harness</a></dt>
<dd>
<dt><a name="fail"
>fail</a></dt>
<dd>
<dt><a name="success"
>success</a></dt>
<dd>
<dt><a name="exception"
>exception</a></dt>
</dl>
<p>All other keys are probably just ignored.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="kill($opts[,_$opts[,_...]])"
><code>kill($opts[, $opts[, ...]])</code></a></h2>
<p>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.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="done($opts)"
><code>done($opts)</code></a></h2>
<p>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.</p>
<h2><a class='u' href='#___top' title='click to go to top of document'
name="safe_qx([$opts,]_@cmds)"
><code>safe_qx([$opts,] @cmds)</code></a></h2>
<p>Variant of spawn that emulates the <code>qx()</code> operator by returning the captured output.</p>
<p>It takes the same arguments as <code>spawn</code> and they have the same basic semantics with the following exceptions:</p>
<dl>
<dt><a name="The_initial_$opts_is_optional."
>The initial $opts is optional.</a></dt>
<dd>
<dt><a name="If_only_a_single_command_is_to_be_run,_the_surrounding_list_reference_can_be_omitted_(see_the_examples_below)."
>If only a single command is to be run, the surrounding list reference can be omitted (see the examples below).</a></dt>
</dl>
<p>If $opts is given, caller must ensure that the output is captured as a scalar reference in <code>$opts-</code>{out}> (possibly by omitting the "out" and "out_append" keys).</p>
<p>Furthermore, the commands should not be backgrounded, so they cannot use '&' nor (e.g. <code>$opts-</code>{pipe_in}>).</p>
<p>If needed <code>$?</code> will be set after the call like for <code>qx()</code>.</p>
<p>Examples:</p>
<pre> # 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')</pre>
<p>Possible known issue: It might not possible to discard stdout and capture stderr instead.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="EXPORTS"
>EXPORTS</a></h1>
<p>Lintian::Command exports nothing by default, but you can export the spawn() and reap() functions.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Originally written by Frank Lichtenheld <djpig@debian.org> for Lintian.</p>
<h1><a class='u' href='#___top' title='click to go to top of document'
name="SEE_ALSO"
>SEE ALSO</a></h1>
<p>lintian(1), IPC::Run</p>
<p class="backlinkbottom"><b><a name="___bottom" href="../index.html" title="All Documents"><<</a></b></p>
<!-- end doc -->
</body></html>
|