GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  IPC::SHELLCMD (3)

.ds Aq ’

NAME

IPC::ShellCmd - Run a command with a given environment and capture output

CONTENTS

SYNOPSIS



    my $isc = IPC::ShellCmd->new(["perl", "Makefile.PL"])
            ->working_dir("/path/to/IPC_ShellCmd-0.01")
            ->stdin(-filename => "/dev/null")
            ->add_envs(PERL5LIB => "/home/mbm/cpanlib/lib/perl5")
            ->add_timers(300 => TERM,
                         360 => KILL,
                         5   => \&display_progress),
            ->chain_prog(
                IPC::ShellCmd::Sudo->new(
                        User => cpanbuild,
                        SetHome => 1,
                    )
            )->run();

    my $stdout = $isc->stdout();
    my $status = $isc->status();



DESCRIPTION

This module comes from the nth time I’ve had to implement a select loop and wanted appropriate sudo/su privilege magic, environment variables that are set in the child, working directories set etc.

It aims to provide a reasonable interface for setting up command execution environment (working directory, environment variables, stdin, stdout and stderr redirection if necessary), but allowing for ssh and sudo and magicking in the appropriate shell quoting.

It tries to be flexible about how you might want to capture output, exit status and other such, but in such a way as it’s hopefully easy to understand and make it work.

Setup method calls are chain-able in a File::Find::Rule kind of a way.

my CI$isc = IPC::ShellCmd->new(\CI@cmd, CI%opts)

Creates a new IPC::ShellCmd object linking to the command and arguments. Possible options:
-nowarn Don’t throw warnings for overwriting values that have already been set
-debug Set the debug level

CI$isc->set_umask(CI$mask)

Sets the umask that this command is going to have, and returns so that it can be chained.

CI$isc->working_dir([CI$path])

Sets the working directory that this command is going to run under, and returns $isc so that it can be chained, or returns the current setting with no arguments.

CI$isc->add_envs(CI$env1 => CI$val1 [, CI$env2 => CI$val2, ...])

Adds environment variables to be setup when the command is run. Returns $isc so that it can be chained.

CI$isc->add_timers(CI$time1 => CI$signame [, CI$time2 => \&handler, ...])

Adds timers to be setup when the command is run. Returns $isc so that it can be chained.

CI$isc->chain_prog(CI$chain_obj, [CI$opt => CI$val, ...])

Adds a chain object, for example IPC::ShellCmd::Sudo->new(User => ’root’) into the chain. Returns $isc so that it can be chained.

Valid options are:
-include-stdin If set, and stdin is a file name (rather than a pipe, open filehandle, or other type of descriptor) then the file will be included in the chain.
-include-stdout As above but with stdout.
-include-stderr As above but with stderr.

CI$isc->stdin($stdin)

CI$isc->stdin($type, CW$stdin)

The 1 argument form takes either
A scalar This is the input to the command in full.
A scalar ref This is a reference to the input that will be passed.
A code ref This is expected to generate the text to send to stdin. It is called with an argument of the number of bytes that the caller wants to read. If it generates more, some may be lost - you have been warned.
The 2 argument form takes a type and then a ref, handle or other. Valid types:
-inherit The argument to this is ignored. If specified this takes stdin from whatever the caller is reading from.
-file The argument to this is a perl filehandle.
-fd The argument to this is a system file descriptor.
-filename The argument to this is a file name which is opened.
Both of these return $isc for chaining. The default is an empty scalar.

CI$isc->stdout()

CI$isc->stderr()

These 0-argument forms return the captured stdout/stderr if the default stdout/stderr handler is set and <B>runB>() has been called. If either has been setup elsewhere, then these will croak() an error.

CI$isc->stdout(CI$value)

CI$isc->stderr(CI$value)

CI$isc->stdout(CI$type, CI$value)

CI$isc->stderr(CI$type, CI$value)

These setup stdout/stderr as appropriate. The forms are similar to the <B>stdinB> method above.

The 1 argument form takes either
A scalar ref This is a reference to a scalar that will have the output appended to it.
A code ref This code will be called (probably more than once) with a scalar of text to be appended which has been read from stdout/stderr.
The 2 argument form takes a type and then a ref, handle or other. Valid types:
-inherit The argument to this is ignored. If specified this takes stdout/stderr from whatever the caller is set to.
-file The argument to this is a perl filehandle.
-fd The argument to this is a system file descriptor.
-filename The argument to this is a file name which is opened.
All of these forms return $isc for chaining. The default is that it will populate an internal variable to be used by the corresponding 0-argument form.

CI$isc->status()

Returns the exit status of the command if it got run.

CI$isc->run()

Runs the command with all the setup that has been done.

BUGS

Apart from the ones that are probably in there and that I don’t know about, this is a very UNIX-centric view of the world, it really should cope with Win32 concepts etc.

SEE ALSO

IPC::ShellCmd::Generic, IPC::ShellCmd::Sudo, IPC::ShellCmd::SSH, IO::Select, IPC::Open3

AUTHORS



    Matthew Byng-Maddick <matthew.byng-maddick@bbc.co.uk> <mbm@colondot.net>

    Tomas Doran (t0m) <bobtfish@bobtfish.net>

    Andrew Ford <andrew@ford-mason.co.uk>



COPYRIGHT

Copyright (c) 2009 the British Broadcasting Corporation.

LICENSE

This library is free software and may be distributed under the same terms as perl itself.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 IPC::SHELLCMD (3) 2013-10-31

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.