1Expect(3) User Contributed Perl Documentation Expect(3)
2
6 Expect - automate interactions with command line programs that expose a
7 text terminal interface.
8
10 use Expect;
11 # create an Expect object by spawning another process
13 my $exp = Expect->spawn($command, @params)
14 or die "Cannot spawn $command: $!\n";
15 # or by using an already opened filehandle (e.g. from Net::Telnet)
17 my $exp = Expect->exp_init(\*FILEHANDLE);
18 # if you prefer the OO mindset:
20 my $exp = Expect->new;
21 $exp->raw_pty(1);
22 $exp->spawn($command, @parameters)
23 or die "Cannot spawn $command: $!\n";
24 # send some string there:
26 $exp->send("string\n");
27 # or, for the filehandle mindset:
29 print $exp "string\n";
30 # then do some pattern matching with either the simple interface
32 $patidx = $exp->expect($timeout, @match_patterns);
33 # or multi-match on several spawned commands with callbacks,
35 # just like the Tcl version
36 $exp->expect($timeout,
37 [ qr/regex1/ => sub { my $exp = shift;
38 $exp->send("response\n");
39 exp_continue; } ],
40 [ "regexp2" , \&callback, @cbparms ],
41 );
42 # if no longer needed, do a soft_close to nicely shut down the command
44 $exp->soft_close();
45 # or be less patient with
47 $exp->hard_close();
48 Expect.pm is built to either spawn a process or take an existing
50 filehandle and interact with it such that normally interactive tasks
51 can be done without operator assistance. This concept makes more sense
52 if you are already familiar with the versatile Tcl version of Expect.
53 The public functions that make up Expect.pm are:
54 Expect->new()
56 Expect::interconnect(@objects_to_be_read_from)
57 Expect::test_handles($timeout, @objects_to_test)
58 Expect::version($version_requested | undef);
59 $object->spawn(@command)
60 $object->clear_accum()
61 $object->set_accum($value)
62 $object->debug($debug_level)
63 $object->exp_internal(0 | 1)
64 $object->notransfer(0 | 1)
65 $object->raw_pty(0 | 1)
66 $object->stty(@stty_modes) # See the IO::Stty docs
67 $object->slave()
68 $object->before();
69 $object->match();
70 $object->after();
71 $object->matchlist();
72 $object->match_number();
73 $object->error();
74 $object->command();
75 $object->exitstatus();
76 $object->pty_handle();
77 $object->do_soft_close();
78 $object->restart_timeout_upon_receive(0 | 1);
79 $object->interact($other_object, $escape_sequence)
80 $object->log_group(0 | 1 | undef)
81 $object->log_user(0 | 1 | undef)
82 $object->log_file("filename" | $filehandle | \&coderef | undef)
83 $object->manual_stty(0 | 1 | undef)
84 $object->match_max($max_buffersize or undef)
85 $object->pid();
86 $object->send_slow($delay, @strings_to_send)
87 $object->set_group(@listen_group_objects | undef)
88 $object->set_seq($sequence,\&function,\@parameters);
89 There are several configurable package variables that affect the
91 behavior of Expect. They are:
92 $Expect::Debug;
94 $Expect::Exp_Internal;
95 $Expect::IgnoreEintr;
96 $Expect::Log_Group;
97 $Expect::Log_Stdout;
98 $Expect::Manual_Stty;
99 $Expect::Multiline_Matching;
100 $Expect::Do_Soft_Close;
101
103 See an explanation of What is Expect <http://code-maven.com/expect>
104 The Expect module is a successor of Comm.pl and a descendent of
106 Chat.pl. It more closely resembles the Tcl Expect language than its
107 predecessors. It does not contain any of the networking code found in
108 Comm.pl. I suspect this would be obsolete anyway given the advent of
109 IO::Socket and external tools such as netcat.
110 Expect.pm is an attempt to have more of a switch() & case feeling to
112 make decision processing more fluid. Three separate types of debugging
113 have been implemented to make code production easier.
114 It is possible to interconnect multiple file handles (and processes)
116 much like Tcl's Expect. An attempt was made to enable all the features
117 of Tcl's Expect without forcing Tcl on the victim programmer :-) .
118 Please, before you consider using Expect, read the FAQs about "I want
120 to automate password entry for su/ssh/scp/rsh/..." and "I want to use
121 Expect to automate [anything with a buzzword]..."
122
124 new Creates a new Expect object, i.e. a pty. You can change parameters
125 on it before actually spawning a command. This is important if you
126 want to modify the terminal settings for the slave. See slave()
127 below. The object returned is actually a reblessed IO::Pty
128 filehandle, so see there for additional methods.
129 Expect->exp_init(\*FILEHANDLE) or
131 Expect->init(\*FILEHANDLE)
132 Initializes $new_handle_object for use with other Expect functions.
133 It must be passed a _reference_ to FILEHANDLE if you want it to
134 work properly. IO::File objects are preferable. Returns a
135 reference to the newly created object.
136 You can use only real filehandles, certain tied filehandles (e.g.
138 Net::SSH2) that lack a fileno() will not work. Net::Telnet objects
139 can be used but have been reported to work only for certain hosts.
140 YMMV.
141 Expect->spawn($command, @parameters) or
143 $object->spawn($command, @parameters) or
144 Expect->new($command, @parameters)
145 Forks and execs $command. Returns an Expect object upon success or
146 "undef" if the fork was unsuccessful or the command could not be
147 found. spawn() passes its parameters unchanged to Perls exec(), so
148 look there for detailed semantics.
149 Note that if spawn cannot exec() the given command, the Expect
151 object is still valid and the next expect() will see "Cannot exec",
152 so you can use that for error handling.
153 Also note that you cannot reuse an object with an already spawned
155 command, even if that command has exited. Sorry, but you have to
156 allocate a new object...
157 $object->debug(0 | 1 | 2 | 3 | undef)
159 Sets debug level for $object. 1 refers to general debugging
160 information, 2 refers to verbose debugging and 0 refers to no
161 debugging. If you call debug() with no parameters it will return
162 the current debugging level. When the object is created the
163 debugging level will match that $Expect::Debug, normally 0.
164 The '3' setting is new with 1.05, and adds the additional
166 functionality of having the _full_ accumulated buffer printed every
167 time data is read from an Expect object. This was implemented by
168 request. I recommend against using this unless you think you need
169 it as it can create quite a quantity of output under some
170 circumstances..
171 $object->exp_internal(1 | 0)
173 Sets/unsets 'exp_internal' debugging. This is similar in nature to
174 its Tcl counterpart. It is extremely valuable when debugging
175 expect() sequences. When the object is created the exp_internal
176 setting will match the value of $Expect::Exp_Internal, normally 0.
177 Returns the current setting if called without parameters. It is
178 highly recommended that you make use of the debugging features lest
179 you have angry code.
180 $object->raw_pty(1 | 0)
182 Set pty to raw mode before spawning. This disables echoing, CR->LF
183 translation and an ugly hack for broken Solaris TTYs (which send
184 <space><backspace> to slow things down) and thus gives a more pipe-
185 like behaviour (which is important if you want to transfer binary
186 content). Note that this must be set before spawning the program.
187 $object->stty(qw(mode1 mode2...))
189 Sets the tty mode for $object's associated terminal to the given
190 modes. Note that on many systems the master side of the pty is not
191 a tty, so you have to modify the slave pty instead, see next item.
192 This needs IO::Stty installed, which is no longer required.
193 $object->slave()
195 Returns a filehandle to the slave part of the pty. Very useful in
196 modifying the terminal settings:
197 $object->slave->stty(qw(raw -echo));
199 Typical values are 'sane', 'raw', and 'raw -echo'. Note that I
201 recommend setting the terminal to 'raw' or 'raw -echo', as this
202 avoids a lot of hassle and gives pipe-like (i.e. transparent)
203 behaviour (without the buffering issue).
204 $object->print(@strings) or
206 $object->send(@strings)
207 Sends the given strings to the spawned command. Note that the
208 strings are not logged in the logfile (see print_log_file) but will
209 probably be echoed back by the pty, depending on pty settings
210 (default is echo) and thus end up there anyway. This must also be
211 taken into account when expect()ing for an answer: the next string
212 will be the command just sent. I suggest setting the pty to raw,
213 which disables echo and makes the pty transparently act like a
214 bidirectional pipe.
215 $object->expect($timeout, @match_patterns)
217 Simple interface
218 Given $timeout in seconds Expect will wait for $object's handle
219 to produce one of the match_patterns, which are matched exactly
220 by default. If you want a regexp match, prefix the pattern with
221 '-re'.
222 $object->expect(15, 'match me exactly','-re','match\s+me\s+exactly');
224 Due to o/s limitations $timeout should be a round number. If
226 $timeout is 0 Expect will check one time to see if $object's
227 handle contains any of the match_patterns. If $timeout is undef
228 Expect will wait forever for a pattern to match.
229 If called in a scalar context, expect() will return the
231 position of the matched pattern within @matched_patterns, or
232 undef if no pattern was matched. This is a position starting
233 from 1, so if you want to know which of an array of
234 @matched_patterns matched you should subtract one from the
235 return value.
236 If called in an array context expect() will return
238 ($matched_pattern_position, $error,
239 $successfully_matching_string, $before_match, and
240 $after_match).
241 $matched_pattern_position will contain the value that would
243 have been returned if expect() had been called in a scalar
244 context.
245 $error is the error that occurred that caused expect() to
247 return. $error will contain a number followed by a string
248 equivalent expressing the nature of the error. Possible values
249 are undef, indicating no error, '1:TIMEOUT' indicating that
250 $timeout seconds had elapsed without a match, '2:EOF'
251 indicating an eof was read from $object, '3: spawn id($fileno)
252 died' indicating that the process exited before matching and
253 '4:$!' indicating whatever error was set in $ERRNO during the
254 last read on $object's handle or during select(). All handles
255 indicated by set_group plus STDOUT will have all data to come
256 out of $object printed to them during expect() if log_group and
257 log_stdout are set.
258 $successfully_matching_string $before_match $after_match
260 Changed from older versions is the regular expression handling.
262 By default now all strings passed to expect() are treated as
263 literals. To match a regular expression pass '-re' as a
264 parameter in front of the pattern you want to match as a
265 regexp.
266 This change makes it possible to match literals and regular
268 expressions in the same expect() call.
269 Also new is multiline matching. ^ will now match the beginning
271 of lines. Unfortunately, because perl doesn't use $/ in
272 determining where lines break using $ to find the end of a line
273 frequently doesn't work. This is because your terminal is
274 returning "\r\n" at the end of every line. One way to check for
275 a pattern at the end of a line would be to use \r?$ instead of
276 $.
277 Example: Spawning telnet to a host, you might look for the
279 escape character. telnet would return to you "\r\nEscape
280 character is '^]'.\r\n". To find this you might use
281 $match='^Escape char.*\.\r?$';
282 $telnet->expect(10,'-re',$match);
284 New more Tcl/Expect-like interface
286 expect($timeout,
287 '-i', [ $obj1, $obj2, ... ],
288 [ $re_pattern, sub { ...; exp_continue; }, @subparms, ],
289 [ 'eof', sub { ... } ],
290 [ 'timeout', sub { ... }, \$subparm1 ],
291 '-i', [ $objn, ...],
292 '-ex', $exact_pattern, sub { ... },
293 $exact_pattern, sub { ...; exp_continue_timeout; },
294 '-re', $re_pattern, sub { ... },
295 '-i', \@object_list, @pattern_list,
296 ...);
297 It's now possible to expect on more than one connection at a
299 time by specifying '"-i"' and a single Expect object or a ref
300 to an array containing Expect objects, e.g.
301 expect($timeout,
303 '-i', $exp1, @patterns_1,
304 '-i', [ $exp2, $exp3 ], @patterns_2_3,
305 )
306 Furthermore, patterns can now be specified as array refs
308 containing [$regexp, sub { ...}, @optional_subprams] . When the
309 pattern matches, the subroutine is called with parameters
310 ($matched_expect_obj, @optional_subparms). The subroutine can
311 return the symbol `exp_continue' to continue the expect
312 matching with timeout starting anew or return the symbol
313 `exp_continue_timeout' for continuing expect without resetting
314 the timeout count.
315 $exp->expect($timeout,
317 [ qr/username: /i, sub { my $self = shift;
318 $self->send("$username\n");
319 exp_continue; }],
320 [ qr/password: /i, sub { my $self = shift;
321 $self->send("$password\n");
322 exp_continue; }],
323 $shell_prompt);
324 `expect' is now exported by default.
326 $object->exp_before() or
328 $object->before()
329 before() returns the 'before' part of the last expect() call. If
330 the last expect() call didn't match anything, exp_before() will
331 return the entire output of the object accumulated before the
332 expect() call finished.
333 Note that this is something different than Tcl Expects before()!!
335 $object->exp_after() or
337 $object->after()
338 returns the 'after' part of the last expect() call. If the last
339 expect() call didn't match anything, exp_after() will return
340 undef().
341 $object->exp_match() or
343 $object->match()
344 returns the string matched by the last expect() call, undef if no
345 string was matched.
346 $object->exp_match_number() or
348 $object->match_number()
349 exp_match_number() returns the number of the pattern matched by the
350 last expect() call. Keep in mind that the first pattern in a list
351 of patterns is 1, not 0. Returns undef if no pattern was matched.
352 $object->exp_matchlist() or
354 $object->matchlist()
355 exp_matchlist() returns a list of matched substrings from the
356 brackets () inside the regexp that last matched.
357 ($object->matchlist)[0] thus corresponds to $1,
358 ($object->matchlist)[1] to $2, etc.
359 $object->exp_error() or
361 $object->error()
362 exp_error() returns the error generated by the last expect() call
363 if no pattern was matched. It is typically useful to examine the
364 value returned by before() to find out what the output of the
365 object was in determining why it didn't match any of the patterns.
366 $object->clear_accum()
368 Clear the contents of the accumulator for $object. This gets rid of
369 any residual contents of a handle after expect() or send_slow()
370 such that the next expect() call will only see new data from
371 $object. The contents of the accumulator are returned.
372 $object->set_accum($value)
374 Sets the content of the accumulator for $object to $value. The
375 previous content of the accumulator is returned.
376 $object->exp_command() or
378 $object->command()
379 exp_command() returns the string that was used to spawn the
380 command. Helpful for debugging and for reused patternmatch
381 subroutines.
382 $object->exp_exitstatus() or
384 $object->exitstatus()
385 Returns the exit status of $object (if it already exited).
386 $object->exp_pty_handle() or
388 $object->pty_handle()
389 Returns a string representation of the attached pty, for example:
390 `spawn id(5)' (pty has fileno 5), `handle id(7)' (pty was
391 initialized from fileno 7) or `STDIN'. Useful for debugging.
392 $object->restart_timeout_upon_receive(0 | 1)
394 If this is set to 1, the expect timeout is retriggered whenever
395 something is received from the spawned command. This allows to
396 perform some aliveness testing and still expect for patterns.
397 $exp->restart_timeout_upon_receive(1);
399 $exp->expect($timeout,
400 [ timeout => \&report_timeout ],
401 [ qr/pattern/ => \&handle_pattern],
402 );
403 Now the timeout isn't triggered if the command produces any kind of
405 output, i.e. is still alive, but you can act upon patterns in the
406 output.
407 $object->notransfer(1 | 0)
409 Do not truncate the content of the accumulator after a match.
410 Normally, the accumulator is set to the remains that come after the
411 matched string. Note that this setting is per object and not per
412 pattern, so if you want to have normal acting patterns that
413 truncate the accumulator, you have to add a
414 $exp->set_accum($exp->after);
416 to their callback, e.g.
418 $exp->notransfer(1);
420 $exp->expect($timeout,
421 # accumulator not truncated, pattern1 will match again
422 [ "pattern1" => sub { my $self = shift;
423 ...
424 } ],
425 # accumulator truncated, pattern2 will not match again
426 [ "pattern2" => sub { my $self = shift;
427 ...
428 $self->set_accum($self->after());
429 } ],
430 );
431 This is only a temporary fix until I can rewrite the pattern
433 matching part so it can take that additional -notransfer argument.
434 Expect::interconnect(@objects);
436 Read from @objects and print to their @listen_groups until an
437 escape sequence is matched from one of @objects and the associated
438 function returns 0 or undef. The special escape sequence 'EOF' is
439 matched when an object's handle returns an end of file. Note that
440 it is not necessary to include objects that only accept data in
441 @objects since the escape sequence is _read_ from an object.
442 Further note that the listen_group for a write-only object is
443 always empty. Why would you want to have objects listening to
444 STDOUT (for example)? By default every member of @objects _as well
445 as every member of its listen group_ will be set to 'raw -echo' for
446 the duration of interconnection. Setting $object->manual_stty()
447 will stop this behavior per object. The original tty settings will
448 be restored as interconnect exits.
449 For a generic way to interconnect processes, take a look at
451 IPC::Run.
452 Expect::test_handles(@objects)
454 Given a set of objects determines which objects' handles have data
455 ready to be read. Returns an array who's members are positions in
456 @objects that have ready handles. Returns undef if there are no
457 such handles ready.
458 Expect::version($version_requested or undef);
460 Returns current version of Expect. As of .99 earlier versions are
461 not supported. Too many things were changed to make versioning
462 possible.
463 $object->interact( "\*FILEHANDLE, $escape_sequence")
465 interact() is essentially a macro for calling interconnect() for
466 connecting 2 processes together. \*FILEHANDLE defaults to \*STDIN
467 and $escape_sequence defaults to undef. Interaction ceases when
468 $escape_sequence is read from FILEHANDLE, not $object. $object's
469 listen group will consist solely of \*FILEHANDLE for the duration
470 of the interaction. \*FILEHANDLE will not be echoed on STDOUT.
471 $object->log_group(0 | 1 | undef)
473 Set/unset logging of $object to its 'listen group'. If set all
474 objects in the listen group will have output from $object printed
475 to them during $object->expect(), $object->send_slow(), and
476 "Expect::interconnect($object , ...)". Default value is on. During
477 creation of $object the setting will match the value of
478 $Expect::Log_Group, normally 1.
479 $object->log_user(0 | 1 | undef) or
481 $object->log_stdout(0 | 1 | undef)
482 Set/unset logging of object's handle to STDOUT. This corresponds to
483 Tcl's log_user variable. Returns current setting if called without
484 parameters. Default setting is off for initialized handles. When
485 a process object is created (not a filehandle initialized with
486 exp_init) the log_stdout setting will match the value of
487 $Expect::Log_Stdout variable, normally 1. If/when you initialize
488 STDIN it is usually associated with a tty which will by default
489 echo to STDOUT anyway, so be careful or you will have multiple
490 echoes.
491 $object->log_file("filename" | $filehandle | \&coderef | undef)
493 Log session to a file. All characters send to or received from the
494 spawned process are written to the file. Normally appends to the
495 logfile, but you can pass an additional mode of "w" to truncate the
496 file upon open():
497 $object->log_file("filename", "w");
499 Returns the logfilehandle.
501 If called with an undef value, stops logging and closes logfile:
503 $object->log_file(undef);
505 If called without argument, returns the logfilehandle:
507 $fh = $object->log_file();
509 Can be set to a code ref, which will be called instead of printing
511 to the logfile:
512 $object->log_file(\&myloggerfunc);
514 $object->print_log_file(@strings)
516 Prints to logfile (if opened) or calls the logfile hook function.
517 This allows the user to add arbitrary text to the logfile. Note
518 that this could also be done as $object->log_file->print() but
519 would only work for log files, not code hooks.
520 $object->set_seq($sequence, \&function, \@function_parameters)
522 During Expect->interconnect() if $sequence is read from $object
523 &function will be executed with parameters @function_parameters. It
524 is _highly recommended_ that the escape sequence be a single
525 character since the likelihood is great that the sequence will be
526 broken into to separate reads from the $object's handle, making it
527 impossible to strip $sequence from getting printed to $object's
528 listen group. \&function should be something like
529 'main::control_w_function' and @function_parameters should be an
530 array defined by the caller, passed by reference to set_seq().
531 Your function should return a non-zero value if execution of
532 interconnect() is to resume after the function returns, zero or
533 undefined if interconnect() should return after your function
534 returns. The special sequence 'EOF' matches the end of file being
535 reached by $object. See interconnect() for details.
536 $object->set_group(@listener_objects)
538 @listener_objects is the list of objects that should have their
539 handles printed to by $object when Expect::interconnect,
540 $object->expect() or $object->send_slow() are called. Calling w/out
541 parameters will return the current list of the listener objects.
542 $object->manual_stty(0 | 1 | undef)
544 Sets/unsets whether or not Expect should make reasonable guesses as
545 to when and how to set tty parameters for $object. Will match
546 $Expect::Manual_Stty value (normally 0) when $object is created. If
547 called without parameters manual_stty() will return the current
548 manual_stty setting.
549 $object->match_max($maximum_buffer_length | undef) or
551 $object->max_accum($maximum_buffer_length | undef)
552 Set the maximum accumulator size for object. This is useful if you
553 think that the accumulator will grow out of hand during expect()
554 calls. Since the buffer will be matched by every match_pattern it
555 may get slow if the buffer gets too large. Returns current value if
556 called without parameters. Not defined by default.
557 $object->notransfer(0 | 1)
559 If set, matched strings will not be deleted from the accumulator.
560 Returns current value if called without parameters. False by
561 default.
562 $object->exp_pid() or
564 $object->pid()
565 Return pid of $object, if one exists. Initialized filehandles will
566 not have pids (of course).
567 $object->send_slow($delay, @strings);
569 print each character from each string of @strings one at a time
570 with $delay seconds before each character. This is handy for
571 devices such as modems that can be annoying if you send them data
572 too fast. After each character $object will be checked to determine
573 whether or not it has any new data ready and if so update the
574 accumulator for future expect() calls and print the output to
575 STDOUT and @listen_group if log_stdout and log_group are
576 appropriately set.
577 Configurable Package Variables:
579 $Expect::Debug
580 Defaults to 0. Newly created objects have a $object->debug() value
581 of $Expect::Debug. See $object->debug();
582 $Expect::Do_Soft_Close
584 Defaults to 0. When destroying objects, soft_close may take up to
585 half a minute to shut everything down. From now on, only
586 hard_close will be called, which is less polite but still gives the
587 process a chance to terminate properly. Set this to '1' for old
588 behaviour.
589 $Expect::Exp_Internal
591 Defaults to 0. Newly created objects have a $object->exp_internal()
592 value of $Expect::Exp_Internal. See $object->exp_internal().
593 $Expect::IgnoreEintr
595 Defaults to 0. If set to 1, when waiting for new data, Expect will
596 ignore EINTR errors and restart the select() call instead.
597 $Expect::Log_Group
599 Defaults to 1. Newly created objects have a $object->log_group()
600 value of $Expect::Log_Group. See $object->log_group().
601 $Expect::Log_Stdout
603 Defaults to 1 for spawned commands, 0 for file handles attached
604 with exp_init(). Newly created objects have a $object->log_stdout()
605 value of $Expect::Log_Stdout. See $object->log_stdout().
606 $Expect::Manual_Stty
608 Defaults to 0. Newly created objects have a $object->manual_stty()
609 value of $Expect::Manual_Stty. See $object->manual_stty().
610 $Expect::Multiline_Matching
612 Defaults to 1. Affects whether or not expect() uses the /m flag for
613 doing regular expression matching. If set to 1 /m is used.
614 This makes a difference when you are trying to match ^ and $. If
616 you have this on you can match lines in the middle of a page of
617 output using ^ and $ instead of it matching the beginning and end
618 of the entire expression. I think this is handy.
619 The $Expect::Multiline_Matching turns on and off Expect's multi-
621 line matching mode. But this only has an effect if you pass in a
622 string, and then use '-re' mode. If you pass in a regular
623 expression value (via qr//), then the qr//'s own flags are
624 preserved irrespective of what it gets interpolated into. There was
625 a bug in Perl 5.8.x where interpolating a regex without /m into a
626 match with /m would incorrectly apply the /m to the inner regex
627 too, but this was fixed in Perl 5.10. The correct behavior, as seen
628 in Perl 5.10, is that if you pass in a regex (via qr//), then
629 $Expect::Multiline_Matching has no effect. So if you pass in a
630 regex, then you must use the qr's flags to control whether it is
631 multiline (which by default it is not, opposite of the default
632 behavior of Expect).
633
635 Lee Eakin <leakin@japh.itg.ti.com> has ported the kibitz script from
636 Tcl/Expect to Perl/Expect.
637 Jeff Carr <jcarr@linuxmachines.com> provided a simple example of how
639 handle terminal window resize events (transmitted via the WINCH signal)
640 in a ssh session.
641 You can find both scripts in the examples/ subdir. Thanks to both!
643 Historical notes:
645 There are still a few lines of code dating back to the inspirational
647 Comm.pl and Chat.pl modules without which this would not have been
648 possible. Kudos to Eric Arnold <Eric.Arnold@Sun.com> and Randal 'Nuke
649 your NT box with one line of perl code' Schwartz<merlyn@stonehenge.com>
650 for making these available to the perl public.
651 As of .98 I think all the old code is toast. No way could this have
653 been done without it though. Special thanks to Graham Barr for helping
654 make sense of the IO::Handle stuff as well as providing the highly
655 recommended IO::Tty module.
656
658 Mark Rogaski <rogaski@att.com> wrote:
659 "I figured that you'd like to know that Expect.pm has been very useful
661 to AT&T Labs over the past couple of years (since I first talked to
662 Austin about design decisions). We use Expect.pm for managing the
663 switches in our network via the telnet interface, and such automation
664 has significantly increased our reliability. So, you can honestly say
665 that one of the largest digital networks in existence (AT&T Frame
666 Relay) uses Expect.pm quite extensively."
667
669 This is a growing collection of things that might help. Please send
670 you questions that are not answered here to RGiersig@cpan.org
671 What systems does Expect run on?
673 Expect itself doesn't have real system dependencies, but the underlying
674 IO::Tty needs pseudoterminals. IO::Stty uses POSIX.pm and Fcntl.pm.
675 I have used it on Solaris, Linux and AIX, others report *BSD and OSF as
677 working. Generally, any modern POSIX Unix should do, but there are
678 exceptions to every rule. Feedback is appreciated.
679 See IO::Tty for a list of verified systems.
681 Can I use this module with ActivePerl on Windows?
683 Up to now, the answer was 'No', but this has changed.
684 You still cannot use ActivePerl, but if you use the Cygwin environment
686 (http://sources.redhat.com), which brings its own perl, and have the
687 latest IO::Tty (v0.05 or later) installed, it should work (feedback
688 appreciated).
689 The examples in the tutorial don't work!
691 The tutorial is hopelessly out of date and needs a serious overhaul. I
692 apologize for this, I have concentrated my efforts mainly on the
693 functionality. Volunteers welcomed.
694 How can I find out what Expect is doing?
696 If you set
697 $Expect::Exp_Internal = 1;
699 Expect will tell you very verbosely what it is receiving and sending,
701 what matching it is trying and what it found. You can do this on a
702 per-command base with
703 $exp->exp_internal(1);
705 You can also set
707 $Expect::Debug = 1; # or 2, 3 for more verbose output
709 or
711 $exp->debug(1);
713 which gives you even more output.
715 I am seeing the output of the command I spawned. Can I turn that off?
717 Yes, just set
718 $Expect::Log_Stdout = 0;
720 to globally disable it or
722 $exp->log_stdout(0);
724 for just that command. 'log_user' is provided as an alias so
726 Tcl/Expect user get a DWIM experience... :-)
727 No, I mean that when I send some text to the spawned process, it gets
729 echoed back and I have to deal with it in the next expect.
730 This is caused by the pty, which has probably 'echo' enabled. A
731 solution would be to set the pty to raw mode, which in general is
732 cleaner for communication between two programs (no more unexpected
733 character translations). Unfortunately this would break a lot of old
734 code that sends "\r" to the program instead of "\n" (translating this
735 is also handled by the pty), so I won't add this to Expect just like
736 that. But feel free to experiment with "$exp->raw_pty(1)".
737 How do I send control characters to a process?
739 A: You can send any characters to a process with the print command. To
740 represent a control character in Perl, use \c followed by the letter.
741 For example, control-G can be represented with "\cG" . Note that this
742 will not work if you single-quote your string. So, to send control-C to
743 a process in $exp, do:
744 print $exp "\cC";
746 Or, if you prefer:
748 $exp->send("\cC");
750 The ability to include control characters in a string like this is
752 provided by Perl, not by Expect.pm . Trying to learn Expect.pm without
753 a thorough grounding in Perl can be very daunting. We suggest you look
754 into some of the excellent Perl learning material, such as the books
755 _Programming Perl_ and _Learning Perl_ by O'Reilly, as well as the
756 extensive online Perl documentation available through the perldoc
757 command.
758 My script fails from time to time without any obvious reason. It seems
760 that I am sometimes loosing output from the spawned program.
761 You could be exiting too fast without giving the spawned program enough
762 time to finish. Try adding $exp->soft_close() to terminate the program
763 gracefully or do an expect() for 'eof'.
764 Alternatively, try adding a 'sleep 1' after you spawn() the program.
766 It could be that pty creation on your system is just slow (but this is
767 rather improbable if you are using the latest IO-Tty).
768 I want to automate password entry for su/ssh/scp/rsh/...
770 You shouldn't use Expect for this. Putting passwords, especially root
771 passwords, into scripts in clear text can mean severe security
772 problems. I strongly recommend using other means. For 'su', consider
773 switching to 'sudo', which gives you root access on a per-command and
774 per-user basis without the need to enter passwords. 'ssh'/'scp' can be
775 set up with RSA authentication without passwords. 'rsh' can use the
776 .rhost mechanism, but I'd strongly suggest to switch to 'ssh'; to
777 mention 'rsh' and 'security' in the same sentence makes an oxymoron.
778 It will work for 'telnet', though, and there are valid uses for it, but
780 you still might want to consider using 'ssh', as keeping cleartext
781 passwords around is very insecure.
782 I want to use Expect to automate [anything with a buzzword]...
784 Are you sure there is no other, easier way? As a rule of thumb, Expect
785 is useful for automating things that expect to talk to a human, where
786 no formal standard applies. For other tasks that do follow a well-
787 defined protocol, there are often better-suited modules that already
788 can handle those protocols. Don't try to do HTTP requests by spawning
789 telnet to port 80, use LWP instead. To automate FTP, take a look at
790 Net::FTP or "ncftp" (http://www.ncftp.org). You don't use a
791 screwdriver to hammer in your nails either, or do you?
792 Is it possible to use threads with Expect?
794 Basically yes, with one restriction: you must spawn() your programs in
795 the main thread and then pass the Expect objects to the handling
796 threads. The reason is that spawn() uses fork(), and perlthrtut:
797 "Thinking of mixing fork() and threads? Please lie down and wait until the feeling passes."
799 I want to log the whole session to a file.
801 Use
802 $exp->log_file("filename");
804 or
806 $exp->log_file($filehandle);
808 or even
810 $exp->log_file(\&log_procedure);
812 for maximum flexibility.
814 Note that the logfile is appended to by default, but you can specify an
816 optional mode "w" to truncate the logfile:
817 $exp->log_file("filename", "w");
819 To stop logging, just call it with a false argument:
821 $exp->log_file(undef);
823 How can I turn off multi-line matching for my regexps?
825 To globally unset multi-line matching for all regexps:
826 $Expect::Multiline_Matching = 0;
828 You can do that on a per-regexp basis by stating "(?-m)" inside the
830 regexp (you need perl5.00503 or later for that).
831 How can I expect on multiple spawned commands?
833 You can use the -i parameter to specify a single object or a list of
834 Expect objects. All following patterns will be evaluated against that
835 list.
836 You can specify -i multiple times to create groups of objects and
838 patterns to match against within the same expect statement.
839 This works just like in Tcl/Expect.
841 See the source example below.
843 I seem to have problems with ptys!
845 Well, pty handling is really a black magic, as it is extremely system
846 dependent. I have extensively revised IO-Tty, so these problems should
847 be gone.
848 If your system is listed in the "verified" list of IO::Tty, you
850 probably have some non-standard setup, e.g. you compiled your Linux-
851 kernel yourself and disabled ptys. Please ask your friendly sysadmin
852 for help.
853 If your system is not listed, unpack the latest version of IO::Tty, do
855 a 'perl Makefile.PL; make; make test; uname "-a"' and send me the
856 results and I'll see what I can deduce from that.
857 I just want to read the output of a process without expect()ing anything.
859 How can I do this?
860 [ Are you sure you need Expect for this? How about qx() or
861 open("prog|")? ]
862 By using expect without any patterns to match.
864 $process->expect(undef); # Forever until EOF
866 $process->expect($timeout); # For a few seconds
867 $process->expect(0); # Is there anything ready on the handle now?
868 Ok, so now how do I get what was read on the handle?
870 $read = $process->before();
871 Where's IO::Pty?
873 Find it on CPAN as IO-Tty, which provides both.
874 How come when I automate the passwd program to change passwords for me
876 passwd dies before changing the password sometimes/every time?
877 What's happening is you are closing the handle before passwd exits.
878 When you close the handle to a process, it is sent a signal (SIGPIPE?)
879 telling it that STDOUT has gone away. The default behavior for
880 processes is to die in this circumstance. Two ways you can make this
881 not happen are:
882 $process->soft_close();
884 This will wait 15 seconds for a process to come up with an EOF by
886 itself before killing it.
887 $process->expect(undef);
889 This will wait forever for the process to match an empty set of
891 patterns. It will return when the process hits an EOF.
892 As a rule, you should always expect() the result of your transaction
894 before you continue with processing.
895 How come when I try to make a logfile with log_file() or set_group() it
897 doesn't print anything after the last time I run expect()?
898 Output is only printed to the logfile/group when Expect reads from the
899 process, during expect(), send_slow() and interconnect(). One way you
900 can force this is to make use of
901 $process->expect(undef);
903 and
905 $process->expect(0);
907 which will make expect() run with an empty pattern set forever or just
909 for an instant to capture the output of $process. The output is
910 available in the accumulator, so you can grab it using
911 $process->before().
912 I seem to have problems with terminal settings, double echoing, etc.
914 Tty settings are a major pain to keep track of. If you find unexpected
915 behavior such as double-echoing or a frozen session, doublecheck the
916 documentation for default settings. When in doubt, handle them yourself
917 using $exp->stty() and manual_stty() functions. As of .98 you
918 shouldn't have to worry about stty settings getting fouled unless you
919 use interconnect or intentionally change them (like doing -echo to get
920 a password).
921 If you foul up your terminal's tty settings, kill any hung processes
923 and enter 'stty sane' at a shell prompt. This should make your terminal
924 manageable again.
925 Note that IO::Tty returns ptys with your systems default setting
927 regarding echoing, CRLF translation etc. and Expect does not change
928 them. I have considered setting the ptys to 'raw' without any
929 translation whatsoever, but this would break a lot of existing things,
930 as '\r' translation would not work anymore. On the other hand, a raw
931 pty works much like a pipe and is more WYGIWYE (what you get is what
932 you expect), so I suggest you set it to 'raw' by yourself:
933 $exp = Expect->new;
935 $exp->raw_pty(1);
936 $exp->spawn(...);
937 To disable echo:
939 $exp->slave->stty(qw(-echo));
941 I'm spawning a telnet/ssh session and then let the user interact with it.
943 But screen-oriented applications on the other side don't work properly.
944 You have to set the terminal screen size for that. Luckily, IO::Pty
945 already has a method for that, so modify your code to look like this:
946 my $exp = Expect->new;
948 $exp->slave->clone_winsize_from(\*STDIN);
949 $exp->spawn("telnet somehost);
950 Also, some applications need the TERM shell variable set so they know
952 how to move the cursor across the screen. When logging in, the remote
953 shell sends a query (Ctrl-Z I think) and expects the terminal to answer
954 with a string, e.g. 'xterm'. If you really want to go that way (be
955 aware, madness lies at its end), you can handle that and send back the
956 value in $ENV{TERM}. This is only a hand-waving explanation, please
957 figure out the details by yourself.
958 I set the terminal size as explained above, but if I resize the window, the
960 application does not notice this.
961 You have to catch the signal WINCH ("window size changed"), change the
962 terminal size and propagate the signal to the spawned application:
963 my $exp = Expect->new;
965 $exp->slave->clone_winsize_from(\*STDIN);
966 $exp->spawn("ssh somehost);
967 $SIG{WINCH} = \&winch;
968 sub winch {
970 $exp->slave->clone_winsize_from(\*STDIN);
971 kill WINCH => $exp->pid if $exp->pid;
972 $SIG{WINCH} = \&winch;
973 }
974 $exp->interact();
976 There is an example file ssh.pl in the examples/ subdir that shows how
978 this works with ssh. Please note that I do strongly object against
979 using Expect to automate ssh login, as there are better way to do that
980 (see ssh-keygen).
981 I noticed that the test uses a string that resembles, but not exactly
983 matches, a well-known sentence that contains every character. What
984 does that mean?
985 That means you are anal-retentive. :-) [Gotcha there!]
986 I get a "Could not assign a pty" error when running as a non-root user on
988 an IRIX box?
989 The OS may not be configured to grant additional pty's (pseudo
990 terminals) to non-root users. /usr/sbin/mkpts should be 4755, not 700
991 for this to work. I don't know about security implications if you do
992 this.
993 How come I don't notice when the spawned process closes its stdin/out/err??
995 You are probably on one of the systems where the master doesn't get an
996 EOF when the slave closes stdin/out/err.
997 One possible solution is when you spawn a process, follow it with a
999 unique string that would indicate the process is finished.
1000 $process = Expect->spawn('telnet somehost; echo ____END____');
1002 And then $process->expect($timeout,'____END____','other','patterns');
1004
1006 How to automate login
1007 my $telnet = Net::Telnet->new("remotehost") # see Net::Telnet
1008 or die "Cannot telnet to remotehost: $!\n";;
1009 my $exp = Expect->exp_init($telnet);
1010 # deprecated use of spawned telnet command
1012 # my $exp = Expect->spawn("telnet localhost")
1013 # or die "Cannot spawn telnet: $!\n";;
1014 my $spawn_ok;
1016 $exp->expect($timeout,
1017 [
1018 qr'login: $',
1019 sub {
1020 $spawn_ok = 1;
1021 my $fh = shift;
1022 $fh->send("$username\n");
1023 exp_continue;
1024 }
1025 ],
1026 [
1027 'Password: $',
1028 sub {
1029 my $fh = shift;
1030 print $fh "$password\n";
1031 exp_continue;
1032 }
1033 ],
1034 [
1035 eof =>
1036 sub {
1037 if ($spawn_ok) {
1038 die "ERROR: premature EOF in login.\n";
1039 } else {
1040 die "ERROR: could not spawn telnet.\n";
1041 }
1042 }
1043 ],
1044 [
1045 timeout =>
1046 sub {
1047 die "No login.\n";
1048 }
1049 ],
1050 '-re', qr'[#>:] $', #' wait for shell prompt, then exit expect
1051 );
1052 How to expect on multiple spawned commands
1054 foreach my $cmd (@list_of_commands) {
1055 push @commands, Expect->spawn($cmd);
1056 }
1057 expect($timeout,
1059 '-i', \@commands,
1060 [
1061 qr"pattern", # find this pattern in output of all commands
1062 sub {
1063 my $obj = shift; # object that matched
1064 print $obj "something\n";
1065 exp_continue; # we don't want to terminate the expect call
1066 }
1067 ],
1068 '-i', $some_other_command,
1069 [
1070 "some other pattern",
1071 sub {
1072 my ($obj, $parmref) = @_;
1073 # ...
1074 # now we exit the expect command
1076 },
1077 \$parm
1078 ],
1079 );
1080 How to propagate terminal sizes
1082 my $exp = Expect->new;
1083 $exp->slave->clone_winsize_from(\*STDIN);
1084 $exp->spawn("ssh somehost);
1085 $SIG{WINCH} = \&winch;
1086 sub winch {
1088 $exp->slave->clone_winsize_from(\*STDIN);
1089 kill WINCH => $exp->pid if $exp->pid;
1090 $SIG{WINCH} = \&winch;
1091 }
1092 $exp->interact();
1094
1096 <http://sourceforge.net/projects/expectperl/> though the source code is
1097 now in GitHub: <https://github.com/jacoby/expect.pm>
1098
1100 There are two mailing lists available, expectperl-announce and
1101 expectperl-discuss, at
1102 http://lists.sourceforge.net/lists/listinfo/expectperl-announce
1104 and
1106 http://lists.sourceforge.net/lists/listinfo/expectperl-discuss
1108
1110 You can use the CPAN Request Tracker http://rt.cpan.org/ and submit new
1111 bugs under
1112 http://rt.cpan.org/Ticket/Create.html?Queue=Expect
1114
1116 (c) 1997 Austin Schutz <ASchutz@users.sourceforge.net> (retired)
1117 expect() interface & functionality enhancements (c) 1999-2006 Roland
1119 Giersig.
1120 This module is now maintained by Dave Jacoby <jacoby@cpan.org>
1122
1124 This module can be used under the same terms as Perl.
1125
1127 THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
1128 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1129 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
1130 IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
1131 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
1132 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
1133 OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1134 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
1135 TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
1136 USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
1137 DAMAGE.
1138 In other words: Use at your own risk. Provided as is. Your mileage
1140 may vary. Read the source, Luke!
1141 And finally, just to be sure:
1143 Any Use of This Product, in Any Manner Whatsoever, Will Increase the
1145 Amount of Disorder in the Universe. Although No Liability Is Implied
1146 Herein, the Consumer Is Warned That This Process Will Ultimately Lead
1147 to the Heat Death of the Universe.
1148perl v5.36.0 2023-01-20 Expect(3)