1Expect(3)             User Contributed Perl Documentation            Expect(3)
2
3
4

NAME

6       Expect - automate interactions with command line programs that expose a
7       text terminal interface.
8

SYNOPSIS

10         use Expect;
11
12         # create an Expect object by spawning another process
13         my $exp = Expect->spawn($command, @params)
14           or die "Cannot spawn $command: $!\n";
15
16         # or by using an already opened filehandle (e.g. from Net::Telnet)
17         my $exp = Expect->exp_init(\*FILEHANDLE);
18
19         # 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
25         # send some string there:
26         $exp->send("string\n");
27
28         # or, for the filehandle mindset:
29         print $exp "string\n";
30
31         # then do some pattern matching with either the simple interface
32         $patidx = $exp->expect($timeout, @match_patterns);
33
34         # 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
43         # if no longer needed, do a soft_close to nicely shut down the command
44         $exp->soft_close();
45
46         # or be less patient with
47         $exp->hard_close();
48
49       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
55         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
90       There are several configurable package variables that affect the
91       behavior of Expect. They are:
92
93         $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

DESCRIPTION

103       See an explanation of What is Expect <http://code-maven.com/expect>
104
105       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
111       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
115       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
119       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

USAGE

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
130       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
137           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
142       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
150           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
154           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
158       $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
165           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
172       $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
181       $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
188       $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
194       $object->slave()
195           Returns a filehandle to the slave part of the pty.  Very useful in
196           modifying the terminal settings:
197
198             $object->slave->stty(qw(raw -echo));
199
200           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
205       $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
216       $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
223                 $object->expect(15, 'match me exactly','-re','match\s+me\s+exactly');
224
225               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
230               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
237               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
242               $matched_pattern_position will contain the value that would
243               have been returned if expect() had been called in a scalar
244               context.
245
246               $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
259               $successfully_matching_string $before_match $after_match
260
261               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
267               This change makes it possible to match literals and regular
268               expressions in the same expect() call.
269
270               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
278               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
283                 $telnet->expect(10,'-re',$match);
284
285           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
298               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
302                expect($timeout,
303                       '-i', $exp1, @patterns_1,
304                       '-i', [ $exp2, $exp3 ], @patterns_2_3,
305                      )
306
307               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
316                $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
325               `expect' is now exported by default.
326
327       $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
334           Note that this is something different than Tcl Expects before()!!
335
336       $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
342       $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
347       $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
353       $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
360       $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
367       $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
373       $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
377       $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
383       $object->exp_exitstatus() or
384       $object->exitstatus()
385           Returns the exit status of $object (if it already exited).
386
387       $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
393       $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
398               $exp->restart_timeout_upon_receive(1);
399               $exp->expect($timeout,
400                            [ timeout => \&report_timeout ],
401                            [ qr/pattern/ => \&handle_pattern],
402                           );
403
404           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
408       $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
415               $exp->set_accum($exp->after);
416
417           to their callback, e.g.
418
419               $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
432           This is only a temporary fix until I can rewrite the pattern
433           matching part so it can take that additional -notransfer argument.
434
435       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
450           For a generic way to interconnect processes, take a look at
451           IPC::Run.
452
453       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
459       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
464       $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
472       $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
480       $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
492       $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
498             $object->log_file("filename", "w");
499
500           Returns the logfilehandle.
501
502           If called with an undef value, stops logging and closes logfile:
503
504             $object->log_file(undef);
505
506           If called without argument, returns the logfilehandle:
507
508             $fh = $object->log_file();
509
510           Can be set to a code ref, which will be called instead of printing
511           to the logfile:
512
513             $object->log_file(\&myloggerfunc);
514
515       $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
521       $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
537       $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
543       $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
550       $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
558       $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
563       $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
568       $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
578   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
583       $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
590       $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
594       $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
598       $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
602       $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
607       $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
611       $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
615           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
620           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

CONTRIBUTIONS

635       Lee Eakin <leakin@japh.itg.ti.com> has ported the kibitz script from
636       Tcl/Expect to Perl/Expect.
637
638       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
642       You can find both scripts in the examples/ subdir.  Thanks to both!
643
644       Historical notes:
645
646       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
652       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

REFERENCES

658       Mark Rogaski <rogaski@att.com> wrote:
659
660       "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

FAQ - Frequently Asked Questions

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
672   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
676       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
680       See IO::Tty for a list of verified systems.
681
682   Can I use this module with ActivePerl on Windows?
683       Up to now, the answer was 'No', but this has changed.
684
685       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
690   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
695   How can I find out what Expect is doing?
696       If you set
697
698         $Expect::Exp_Internal = 1;
699
700       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
704         $exp->exp_internal(1);
705
706       You can also set
707
708         $Expect::Debug = 1;  # or 2, 3 for more verbose output
709
710       or
711
712         $exp->debug(1);
713
714       which gives you even more output.
715
716   I am seeing the output of the command I spawned.  Can I turn that off?
717       Yes, just set
718
719         $Expect::Log_Stdout = 0;
720
721       to globally disable it or
722
723          $exp->log_stdout(0);
724
725       for just that command.  'log_user' is provided as an alias so
726       Tcl/Expect user get a DWIM experience... :-)
727
728   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
738   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
745         print $exp "\cC";
746
747       Or, if you prefer:
748
749         $exp->send("\cC");
750
751       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
759   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
765       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
769   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
779       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
783   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
793   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
798         "Thinking of mixing fork() and threads?  Please lie down and wait until the feeling passes."
799
800   I want to log the whole session to a file.
801       Use
802
803         $exp->log_file("filename");
804
805       or
806
807         $exp->log_file($filehandle);
808
809       or even
810
811         $exp->log_file(\&log_procedure);
812
813       for maximum flexibility.
814
815       Note that the logfile is appended to by default, but you can specify an
816       optional mode "w" to truncate the logfile:
817
818         $exp->log_file("filename", "w");
819
820       To stop logging, just call it with a false argument:
821
822         $exp->log_file(undef);
823
824   How can I turn off multi-line matching for my regexps?
825       To globally unset multi-line matching for all regexps:
826
827         $Expect::Multiline_Matching = 0;
828
829       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
832   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
837       You can specify -i multiple times to create groups of objects and
838       patterns to match against within the same expect statement.
839
840       This works just like in Tcl/Expect.
841
842       See the source example below.
843
844   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
849       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
854       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
858   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
863       By using expect without any patterns to match.
864
865         $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
869   Ok, so now how do I get what was read on the handle?
870         $read = $process->before();
871
872   Where's IO::Pty?
873       Find it on CPAN as IO-Tty, which provides both.
874
875   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
883         $process->soft_close();
884
885       This will wait 15 seconds for a process to come up with an EOF by
886       itself before killing it.
887
888         $process->expect(undef);
889
890       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
893       As a rule, you should always expect() the result of your transaction
894       before you continue with processing.
895
896   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
902         $process->expect(undef);
903
904       and
905
906         $process->expect(0);
907
908       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
913   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
922       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
926       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
934         $exp = Expect->new;
935         $exp->raw_pty(1);
936         $exp->spawn(...);
937
938       To disable echo:
939
940         $exp->slave->stty(qw(-echo));
941
942   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
947         my $exp = Expect->new;
948         $exp->slave->clone_winsize_from(\*STDIN);
949         $exp->spawn("telnet somehost);
950
951       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
959   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
964         my $exp = Expect->new;
965         $exp->slave->clone_winsize_from(\*STDIN);
966         $exp->spawn("ssh somehost);
967         $SIG{WINCH} = \&winch;
968
969         sub winch {
970           $exp->slave->clone_winsize_from(\*STDIN);
971           kill WINCH => $exp->pid if $exp->pid;
972           $SIG{WINCH} = \&winch;
973         }
974
975         $exp->interact();
976
977       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
982   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
987   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
994   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
998       One possible solution is when you spawn a process, follow it with a
999       unique string that would indicate the process is finished.
1000
1001         $process = Expect->spawn('telnet somehost; echo ____END____');
1002
1003       And then $process->expect($timeout,'____END____','other','patterns');
1004

Source Examples

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
1011         # deprecated use of spawned telnet command
1012         # my $exp = Expect->spawn("telnet localhost")
1013         #   or die "Cannot spawn telnet: $!\n";;
1014
1015         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
1053   How to expect on multiple spawned commands
1054         foreach my $cmd (@list_of_commands) {
1055           push @commands, Expect->spawn($cmd);
1056         }
1057
1058         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
1075               # now we exit the expect command
1076             },
1077             \$parm
1078            ],
1079           );
1080
1081   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
1087         sub winch {
1088           $exp->slave->clone_winsize_from(\*STDIN);
1089           kill WINCH => $exp->pid if $exp->pid;
1090           $SIG{WINCH} = \&winch;
1091         }
1092
1093         $exp->interact();
1094

HOMEPAGE

1096       <http://sourceforge.net/projects/expectperl/> though the source code is
1097       now in GitHub: <https://github.com/jacoby/expect.pm>
1098

MAILING LISTS

1100       There are two mailing lists available, expectperl-announce and
1101       expectperl-discuss, at
1102
1103         http://lists.sourceforge.net/lists/listinfo/expectperl-announce
1104
1105       and
1106
1107         http://lists.sourceforge.net/lists/listinfo/expectperl-discuss
1108

BUG TRACKING

1110       You can use the CPAN Request Tracker http://rt.cpan.org/ and submit new
1111       bugs under
1112
1113         http://rt.cpan.org/Ticket/Create.html?Queue=Expect
1114

AUTHORS

1116       (c) 1997 Austin Schutz <ASchutz@users.sourceforge.net> (retired)
1117
1118       expect() interface & functionality enhancements (c) 1999-2006 Roland
1119       Giersig.
1120
1121       This module is now maintained by Dave Jacoby <jacoby@cpan.org>
1122

LICENSE

1124       This module can be used under the same terms as Perl.
1125

DISCLAIMER

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
1139       In other words: Use at your own risk.  Provided as is.  Your mileage
1140       may vary.  Read the source, Luke!
1141
1142       And finally, just to be sure:
1143
1144       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.
1148
1149
1150
1151perl v5.32.0                      2020-07-28                         Expect(3)
Impressum