- NAME
- SYNOPSIS
- DESCRIPTION
- ENVIRONMENT
- BUGS

# NAME

ActiveState::Run - Collection of small utility functions

# SYNOPSIS

     use ActiveState::Run qw(run);
     run("ls -l");

# DESCRIPTION

This module provides a collection of small utility functions for running external programs.

The following functions are provided:

decode_status( )
decode_status( $rc )

  Will decode the given return code (defaults to $?) and return the exit value, the signal it was killed with, and if it dumped core.

  In scalar context, it will return a string explaining what happened, or an empty string if no error occured.

        my $foo = `ls`;
        my $err = decode_status;
        die "ls failed: $err" if $err;

  In array context, it will return a list of key/value pairs containing:

  WIFEXITED

    True when the status code indicates normal termination.

  WEXITSTATUS

    If WIFEXITED, this will contain the low-order 8 bits of the status value the child passed to exit or returned from main.

  WIFSIGNALED

    Non-zero if process was terminated by a signal.

  WTERMSIG

    If WIFSIGNALED, the terminating signal.

  WIFSTOPPED

    Non-zero if the process was stopped.

  WSTOPSIG

    If WIFSTOPPED, the signal that stopped the process.

  WCOREDUMP

    Nonzero if the process dumped core.

  Example:

        my $foo = `ls`;
        my %err = decode_status;
        die "ls dumped core" if $err{WCOREDUMP};

run( $cmd, @args )

  Works like the builtin system() but will by default print commands to stdout before it execute them and raise an exception (die) if the command fails (returns non-zero status). Like for the command specifications for make(1), you can prefix the command with "@" to suppress the echo and with "-" to suppress the status check.

  The environment variables AS_RUN_SILENT and AS_RUN_PREFIX influence printing as well, see "ENVIRONMENT".

run_ex( %opt )

  The extended version of the run function with many additional ways to control the how the command runs, but otherwise it acts as run().

  The following options are recognized:

  cmd => $cmd
  cmd => [$cmd, @args]

    Specify the command line to run. It does not support the '@' and '-' prefixes that the run() command allow. This option is not optional :)

  exe => $path

    Only use this if you want to override what executable actually runs. Can be used to lie about what program actually runs, as this allow argv[0] to be different than the actual command.

  cwd => $path

    Make this the current directory of the process. By default, the process shares the parent's current directory.

  env => \%hash

    Override the environment for the process.

  env_hide => \@keys

    List of environment variables that will not be passed to the kid. You might pass this as `[keys %ENV]` if you want the process to start out with an environment that only consist of what you passed in with the `env` option.

  stdin => $filehandle

    Make the new process run with stdin from the given filehandle. If not given the process will be started with /dev/null as its input. If you want the process to inherit the input of the parent you need to pass `*STDIN` explictly.

  output => $path

    Redirect the combined STDOUT and STDERR to the given file. The command will croak if the file can't be opened. If not specified, then the STDOUT and STDERR of the process is simply inherited from the parent.

  silent => $bool

    If TRUE don't echo commands as they are executed.

  ignore_err => $bool

    If TRUE don't croak if the command exits with a non-zero status.

  nice => $bool

    Be nice!

  tee => $bool

    If TRUE send the output captured in the `output` file to the current STDOUT as well. No effect unless `output` is specified.

  new_group => $bool

    If TRUE start a new process group for the process.

  limit_time => $seconds

    Kill the process (or the process group if `new_group` was specified) if it runs for longer than the specified number of seconds.

  limit_output => $megabytes

    Kill the process (or the process group if `new_group` was specified) if it output file grows bigger than the specified number of mega bytes. No effect unless `output` was specified.

  limit_cpu => $seconds
  limit_XXX => $megabytes

    Other limits might also be passed which will set how much resources the process is allowed to use. The unit for all size limits are megabytes. See `BSD::Resource` for allowed values. Also consult the `ulimit` command in you shell.

shell_quote( @args )

  Will quote the arguments provided so that they can be passed to the command shell without interpretation by the shell. This is useful with run() when you can't provide separate @args, e.g.:

         run(shell_quote("rm", "-f", @files) . " >dev/null");

  In list context it returns the same number of values as arguments passed in. Only those arg values that need quoting will be quoted.

  In scalar context it will return a single string with all the quoted @args separated by space.

  In void context it will attempt inline modification of the @args passed.

# ENVIRONMENT

If the AS_RUN_SILENT environment variable is TRUE, then printing of the command about to run for run() is suppressed.

If the AS_RUN_PREFIX environment variable is set, then the printed command is prefixed with the given string. If AS_RUN_SILENT is TRUE, then this value is ignored.

# BUGS

none.