NAME Sys::Cmd - run a system command or spawn a system processes VERSION 0.81.4 (2014-02-14) 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 a CODE reference, or cannot be 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 a CODE reference or cannot be 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 or CODE reference 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 , based heavily on Git::Repository::Command by Philippe Bruhat (BooK). COPYRIGHT AND LICENSE Copyright 2011-2014 Mark Lawrence 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.