Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IPC::ShellCmd(3)      User Contributed Perl Documentation     IPC::ShellCmd(3)

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

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 $isc = IPC::ShellCmd->new(\@cmd, %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

   $isc->set_umask($mask)
       Sets the	umask that this	command	is going to have, and returns  so that
       it can be chained.

   $isc->working_dir([$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.

   $isc->add_envs($env1	=> $val1 [, $env2 => $val2, ...])
       Adds environment	variables to be	setup when the command is run.
       Returns $isc so that it can be chained.

   $isc->add_timers($time1 => $signame [, $time2 => \_handler, ...])
       Adds timers to be setup when the	command	is run.	 Returns $isc so that
       it can be chained.

   $isc->chain_prog($chain_obj,	[$opt => $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.

   $isc->stdin($stdin)
   $isc->stdin($type, $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.

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

   $isc->stdout($value)
   $isc->stderr($value)
   $isc->stdout($type, $value)
   $isc->stderr($type, $value)
       These setup stdout/stderr as appropriate. The forms are similar to the
       stdin 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.

   $isc->status()
       Returns the exit	status of the command if it got	run.

   $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.

perl v5.32.1			  2013-10-31		      IPC::ShellCmd(3)

NAME | SYNOPSIS | DESCRIPTION | BUGS | SEE ALSO | AUTHORS | COPYRIGHT | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IPC::ShellCmd&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help