/ 
Sys-Cmd-0.80.3_2
River stage one • 2 direct dependents • 2 total dependents
/ Sys::Cmd

NAME

Sys::Cmd - run a system command or spawn a system processes

VERSION

0.80.3 (2013-12-15) Development release

SYNOPSIS

use Sys::Cmd qw/run spawn/;

# Get command output, raise exception on failure:
$output = run(@cmd);

# Feed command some input, get output as lines,
# raise exception on failure:
@output = run(@cmd, { input => 'feedme' });

# Spawn and interact with a process somewhere else:
$proc = spawn( @cmd, { dir => '/' , encoding => 'iso-8859-3'} );

while (my $line = $proc->stdout->getline) {
    $proc->stdin->print("thanks");
}

my @errors = $proc->stderr->getlines;

$proc->close();       # Finished talking
$proc->wait_child();  # Cleanup

# read exit information
$proc->exit();      # exit status
$proc->signal();    # signal
$proc->core();      # core dumped? (boolean)

DESCRIPTION

Sys::Cmd lets you run system commands and capture their output, or spawn and interact with a system process through its STDIN, STDOUT, and STDERR file handles. The following functions are exported on demand by this module:

run( @cmd, [\%opt] ) => $output | @output

Execute @cmd and return what the command sent to its STDOUT, raising an exception in the event of error. In array context returns a list instead of a plain string.

The first element of @cmd will be looked up using File::Which if it is not found as a relative file name. The command input and environment can be modified with an optional hashref containing the following key/values:

dir

The working directory the command will be run in.

encoding

An string value identifying the encoding of the input/output file-handles. Defaults to 'utf8'.

env

A hashref containing key/values to be added to the current environment at run-time. If a key has an undefined value then the key is removed from the environment altogether.

input

A string which is fed to the command via its standard input, which is then closed.

runx( @cmd, [\%opt] ) => $outerrput | @outerrput

The same as the run function but with the command's STDERR output appended to the STDOUT output.

spawn( @cmd, [\%opt] ) => Sys::Cmd

Return a Sys::Cmd object (documented below) representing the process running @cmd, with attributes set according to the optional \%opt hashref. The first element of the @cmd array is looked up using File::Which if it is not found in the file-system as a relative file name.

Sys::Cmd objects can of course be created using the standard new constructor if you prefer that to the spawn function:

$proc = Sys::Cmd->new(
    cmd => \@cmd,
    dir => '/',
    env => { SOME => 'VALUE' },
    enc => 'iso-8859-3',
    input => 'feedme',
    on_exit => sub {
        my $proc = shift;
        print $proc->pid .' exited with '. $proc->exit;
    },
);

Note that Sys::Cmd objects created this way will not lookup the command using File::Which the way the run, runx and spawn functions do.

Sys::Cmd uses Log::Any debug calls for logging purposes.

CONSTRUCTOR

new(%args) => Sys::Cmd

Spawns a process based on %args. %args must contain at least a cmd value, and optionally encoding, env, dir and input values as defined as attributes below.

If an on_exit subref argument is provided a SIGCHLD handler will be installed (process wide!) which is called asynchronously (with the Sys::Cmd object as first argument) when the child exits.

ATTRIBUTES

All attributes are read-only.

cmd

An array ref containing the command and its arguments.

dir

The working directory the command will be run in.

encoding

An string value identifying the encoding of the input/output file-handles. Defaults to 'utf8'.

env

A hashref containing key/values to be added to the current environment at run-time. If a key has an undefined value then the key is removed from the environment altogether.

input

A string which is fed to the command via its standard input, which is then closed. This is a shortcut for printing to, and closing the command's stdin file-handle. An empty string will close the command's standard input without writing to it. On some systems, some commands may close standard input on startup, which will cause a SIGPIPE when trying to write to it. This will raise an exception.

pid

The command's process ID.

stdin

The command's STDIN file handle, based on IO::Handle so you can call print() etc methods on it. Autoflush is automatically enabled on this handle.

stdout

The command's STDOUT file handle, based on IO::Handle so you can call getline() etc methods on it.

stderr

The command's STDERR file handle, based on IO::Handle so you can call getline() etc methods on it.

exit

The command's exit value, shifted by 8 (see "perldoc -f system"). Set either when a SIGCHLD is received or after a call to wait_child().

signal

The signal number (if any) that terminated the command, bitwise-added with 127 (see "perldoc -f system"). Set either when a SIGCHLD is received or after a call to wait_child().

core

A boolean indicating the process core was dumped. Set either when a SIGCHLD is received or after a call to wait_child().

METHODS

cmdline => @list | $str

In array context returns a list of the command and its arguments. In scalar context returns a string of the command and its arguments joined together by spaces.

close()

Close all pipes to the child process. This method is automatically called when the Sys::Cmd object is destroyed. Annoyingly, this means that in the following example $fh will be closed when you tried to use it:

my $fh = Sys::Cmd->new( %args )->stdout;

So you have to keep track of the Sys::Cmd object manually.

wait_child()

Wait for the child to exit and collect the exit status. This method is resposible for setting the exit, signal and core attributes.

SEE ALSO

Sys::Cmd::Template

ALTERNATIVES

AnyEvent::Run, AnyEvent::Util, Argv, Capture::Tiny, Child, Forks::Super, IO::Pipe, IPC::Capture, IPC::Cmd, IPC::Command::Multiplex, IPC::Exe, IPC::Open3, IPC::Open3::Simple, IPC::Run, IPC::Run3, IPC::RunSession::Simple, IPC::ShellCmd, IPC::System::Simple, POE::Pipe::TwoWay, Proc::Background, Proc::Fork, Proc::Spawn, Spawn::Safe, System::Command

SUPPORT

This distribution is managed via github:

https://github.com/mlawren/sys-cmd/tree/devel

This distribution follows the semantic versioning model:

http://semver.org/

Code is tidied up on Git commit using githook-perltidy:

http://github.com/mlawren/githook-perltidy

AUTHOR

Mark Lawrence <nomad@null.net>, based heavily on Git::Repository::Command by Philippe Bruhat (BooK).

COPYRIGHT AND LICENSE

Copyright 2011-2012 Mark Lawrence <nomad@null.net>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.