README
1NAME
2 IPC::ShellCmd - Run a command with a given environment and capture
3 output
4
5SYNOPSIS
6 my $isc = IPC::ShellCmd->new(["perl", "Makefile.PL"])
7 ->working_dir("/path/to/IPC_ShellCmd-0.01")
8 ->stdin(-filename => "/dev/null")
9 ->add_envs(PERL5LIB => "/home/mbm/cpanlib/lib/perl5")
10 ->add_timers(300 => 'TERM',
11 360 => 'KILL',
12 5 => \&display_progress),
13 ->chain_prog(
14 IPC::ShellCmd::Sudo->new(
15 User => 'cpanbuild',
16 SetHome => 1,
17 )
18 )->run();
19
20 my $stdout = $isc->stdout();
21 my $status = $isc->status();
22
23DESCRIPTION
24 This module comes from the nth time I've had to implement a select loop
25 and wanted appropriate sudo/su privilege magic, environment variables
26 that are set in the child, working directories set etc.
27
28 It aims to provide a reasonable interface for setting up command
29 execution environment (working directory, environment variables, stdin,
30 stdout and stderr redirection if necessary), but allowing for ssh and
31 sudo and magicking in the appropriate shell quoting.
32
33 It tries to be flexible about how you might want to capture output, exit
34 status and other such, but in such a way as it's hopefully easy to
35 understand and make it work.
36
37 Setup method calls are chain-able in a File::Find::Rule kind of a way.
38
39 my *$isc* = IPC::ShellCmd->new(\*@cmd*, *%opts*)
40 Creates a new IPC::ShellCmd object linking to the command and arguments.
41 Possible options:
42
43 "-nowarn"
44 Don't throw warnings for overwriting values that have already been
45 set
46
47 "-debug"
48 Set the debug level
49
50 *$isc*->set_umask(*$mask*)
51 Sets the umask that this command is going to have, and returns ** so
52 that it can be chained.
53
54 *$isc*->working_dir([*$path*])
55 Sets the working directory that this command is going to run under, and
56 returns *$isc* so that it can be chained, or returns the current setting
57 with no arguments.
58
59 *$isc*->add_envs(*$env1* => *$val1* [, *$env2* => *$val2*, ...])
60 Adds environment variables to be setup when the command is run. Returns
61 *$isc* so that it can be chained.
62
63 *$isc*->add_timers(*$time1* => *$signame* [, *$time2* => \*&handler*, ...])
64 Adds timers to be setup when the command is run. Returns *$isc* so that
65 it can be chained.
66
67 *$isc*->chain_prog(*$chain_obj*, [*$opt* => *$val*, ...])
68 Adds a chain object, for example IPC::ShellCmd::Sudo->new(User =>
69 'root') into the chain. Returns *$isc* so that it can be chained.
70
71 Valid options are:
72
73 "-include-stdin"
74 If set, and stdin is a file name (rather than a pipe, open
75 filehandle, or other type of descriptor) then the file will be
76 included in the chain.
77
78 "-include-stdout"
79 As above but with stdout.
80
81 "-include-stderr"
82 As above but with stderr.
83
84 *$isc*->stdin($stdin)
85 *$isc*->stdin($type, $stdin)
86 The 1 argument form takes either
87
88 A scalar
89 This is the input to the command in full.
90
91 A scalar ref
92 This is a reference to the input that will be passed.
93
94 A code ref
95 This is expected to generate the text to send to stdin. It is called
96 with an argument of the number of bytes that the caller wants to
97 read. If it generates more, some may be lost - you have been warned.
98
99 The 2 argument form takes a type and then a ref, handle or other. Valid
100 types:
101
102 "-inherit"
103 The argument to this is ignored. If specified this takes stdin from
104 whatever the caller is reading from.
105
106 "-file"
107 The argument to this is a perl filehandle.
108
109 "-fd"
110 The argument to this is a system file descriptor.
111
112 "-filename"
113 The argument to this is a file name which is opened.
114
115 Both of these return *$isc* for chaining. The default is an empty
116 scalar.
117
118 *$isc*->stdout()
119 *$isc*->stderr()
120 These 0-argument forms return the captured stdout/stderr if the default
121 stdout/stderr handler is set and run() has been called. If either has
122 been setup elsewhere, then these will croak() an error.
123
124 *$isc*->stdout(*$value*)
125 *$isc*->stderr(*$value*)
126 *$isc*->stdout(*$type*, *$value*)
127 *$isc*->stderr(*$type*, *$value*)
128 These setup stdout/stderr as appropriate. The forms are similar to the
129 stdin method above.
130
131 The 1 argument form takes either
132
133 A scalar ref
134 This is a reference to a scalar that will have the output appended
135 to it.
136
137 A code ref
138 This code will be called (probably more than once) with a scalar of
139 text to be appended which has been read from stdout/stderr.
140
141 The 2 argument form takes a type and then a ref, handle or other. Valid
142 types:
143
144 "-inherit"
145 The argument to this is ignored. If specified this takes
146 stdout/stderr from whatever the caller is set to.
147
148 "-file"
149 The argument to this is a perl filehandle.
150
151 "-fd"
152 The argument to this is a system file descriptor.
153
154 "-filename"
155 The argument to this is a file name which is opened.
156
157 All of these forms return *$isc* for chaining. The default is that it
158 will populate an internal variable to be used by the corresponding
159 0-argument form.
160
161 *$isc*->status()
162 Returns the exit status of the command if it got run.
163
164 *$isc*->run()
165 Runs the command with all the setup that has been done.
166
167BUGS
168 Apart from the ones that are probably in there and that I don't know
169 about, this is a very UNIX-centric view of the world, it really should
170 cope with Win32 concepts etc.
171
172SEE ALSO
173 IPC::ShellCmd::Generic, IPC::ShellCmd::Sudo, IPC::ShellCmd::SSH,
174 IO::Select, IPC::Open3
175
176AUTHORS
177 Matthew Byng-Maddick <matthew.byng-maddick@bbc.co.uk> <mbm@colondot.net>
178
179 Tomas Doran (t0m) <bobtfish@bobtfish.net>
180
181 Andrew Ford <andrew@ford-mason.co.uk>
182
183COPYRIGHT
184 Copyright (c) 2009 the British Broadcasting Corporation.
185
186LICENSE
187 This library is free software and may be distributed under the same
188 terms as perl itself.
189
190