Expect5.16 man page on MacOSX

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
MacOSX logo
[printable version]

Expect(3)	      User Contributed Perl Documentation	     Expect(3)

NAME
       Expect.pm - Expect for Perl

VERSION
       1.21

SYNOPSIS
	 use Expect;

	 # create an Expect object by spawning another process
	 my $exp = Expect->spawn($command, @params)
	   or die "Cannot spawn $command: $!\n";

	 # or by using an already opened filehandle (e.g. from Net::Telnet)
	 my $exp = Expect->exp_init(\*FILEHANDLE);

	 # if you prefer the OO mindset:
	 my $exp = new Expect;
	 $exp->raw_pty(1);
	 $exp->spawn($command, @parameters)
	   or die "Cannot spawn $command: $!\n";

	 # send some string there:
	 $exp->send("string\n");

	 # or, for the filehandle mindset:
	 print $exp "string\n";

	 # then do some pattern matching with either the simple interface
	 $patidx = $exp->expect($timeout, @match_patterns);

	 # or multi-match on several spawned commands with callbacks,
	 # just like the Tcl version
	 $exp->expect($timeout,
		      [ qr/regex1/ => sub { my $exp = shift;
					    $exp->send("response\n");
					    exp_continue; } ],
		      [ "regexp2" , \&callback, @cbparms ],
		     );

	 # if no longer needed, do a soft_close to nicely shut down the command
	 $exp->soft_close();

	 # or be less patient with
	 $exp->hard_close();

       Expect.pm is built to either spawn a process or take an existing
       filehandle and interact with it such that normally interactive tasks
       can be done without operator assistance. This concept makes more sense
       if you are already familiar with the versatile Tcl version of Expect.
       The public functions that make up Expect.pm are:

	 Expect->new()
	 Expect::interconnect(@objects_to_be_read_from)
	 Expect::test_handles($timeout, @objects_to_test)
	 Expect::version($version_requested | undef);
	 $object->spawn(@command)
	 $object->clear_accum()
	 $object->set_accum($value)
	 $object->debug($debug_level)
	 $object->exp_internal(0 | 1)
	 $object->notransfer(0 | 1)
	 $object->raw_pty(0 | 1)
	 $object->stty(@stty_modes) # See the IO::Stty docs
	 $object->slave()
	 $object->before();
	 $object->match();
	 $object->after();
	 $object->matchlist();
	 $object->match_number();
	 $object->error();
	 $object->command();
	 $object->exitstatus();
	 $object->pty_handle();
	 $object->do_soft_close();
	 $object->restart_timeout_upon_receive(0 | 1);
	 $object->interact($other_object, $escape_sequence)
	 $object->log_group(0 | 1 | undef)
	 $object->log_user(0 | 1 | undef)
	 $object->log_file("filename" | $filehandle | \&coderef | undef)
	 $object->manual_stty(0 | 1 | undef)
	 $object->match_max($max_buffersize or undef)
	 $object->pid();
	 $object->send_slow($delay, @strings_to_send)
	 $object->set_group(@listen_group_objects | undef)
	 $object->set_seq($sequence,\&function,\@parameters);

       There are several configurable package variables that affect the
       behavior of Expect. They are:

	 $Expect::Debug;
	 $Expect::Exp_Internal;
	 $Expect::IgnoreEintr;
	 $Expect::Log_Group;
	 $Expect::Log_Stdout;
	 $Expect::Manual_Stty;
	 $Expect::Multiline_Matching;
	 $Expect::Do_Soft_Close;

DESCRIPTION
       The Expect module is a successor of Comm.pl and a descendent of
       Chat.pl. It more closely ressembles the Tcl Expect language than its
       predecessors. It does not contain any of the networking code found in
       Comm.pl. I suspect this would be obsolete anyway given the advent of
       IO::Socket and external tools such as netcat.

       Expect.pm is an attempt to have more of a switch() & case feeling to
       make decision processing more fluid.  Three separate types of debugging
       have been implemented to make code production easier.

       It is possible to interconnect multiple file handles (and processes)
       much like Tcl's Expect. An attempt was made to enable all the features
       of Tcl's Expect without forcing Tcl on the victim programmer :-) .

       Please, before you consider using Expect, read the FAQs about "I want
       to automate password entry for su/ssh/scp/rsh/..." and "I want to use
       Expect to automate [anything with a buzzword]..."

USAGE
       new Expect ()
	   Creates a new Expect object, i.e. a pty.  You can change parameters
	   on it before actually spawning a command.  This is important if you
	   want to modify the terminal settings for the slave.	See slave()
	   below.  The object returned is actually a reblessed IO::Pty
	   filehandle, so see there for additional methods.

       Expect->exp_init(\*FILEHANDLE) or
       Expect->init(\*FILEHANDLE)
	   Initializes $new_handle_object for use with other Expect functions.
	   It must be passed a _reference_ to FILEHANDLE if you want it to
	   work properly.  IO::File objects are preferable. Returns a
	   reference to the newly created object.

	   You can use only real filehandles, certain tied filehandles (e.g.
	   Net::SSH2) that lack a fileno() will not work. Net::Telnet objects
	   can be used but have been reported to work only for certain hosts.
	   YMMV.

       Expect->spawn($command, @parameters) or
       $object->spawn($command, @parameters) or
       new Expect ($command, @parameters)
	   Forks and execs $command. Returns an Expect object upon success or
	   "undef" if the fork was unsuccessful or the command could not be
	   found.  spawn() passes its parameters unchanged to Perls exec(), so
	   look there for detailed semantics.

	   Note that if spawn cannot exec() the given command, the Expect
	   object is still valid and the next expect() will see "Cannot exec",
	   so you can use that for error handling.

	   Also note that you cannot reuse an object with an already spawned
	   command, even if that command has exited.  Sorry, but you have to
	   allocate a new object...

       $object->debug(0 | 1 | 2 | 3 | undef)
	   Sets debug level for $object. 1 refers to general debugging
	   information, 2 refers to verbose debugging and 0 refers to no
	   debugging. If you call debug() with no parameters it will return
	   the current debugging level.	 When the object is created the
	   debugging level will match that $Expect::Debug, normally 0.

	   The '3' setting is new with 1.05, and adds the additional
	   functionality of having the _full_ accumulated buffer printed every
	   time data is read from an Expect object. This was implemented by
	   request. I recommend against using this unless you think you need
	   it as it can create quite a quantity of output under some
	   circumstances..

       $object->exp_internal(1 | 0)
	   Sets/unsets 'exp_internal' debugging. This is similar in nature to
	   its Tcl counterpart. It is extremely valuable when debugging
	   expect() sequences.	When the object is created the exp_internal
	   setting will match the value of $Expect::Exp_Internal, normally 0.
	   Returns the current setting if called without parameters. It is
	   highly recommended that you make use of the debugging features lest
	   you have angry code.

       $object->raw_pty(1 | 0)
	   Set pty to raw mode before spawning.	 This disables echoing, CR->LF
	   translation and an ugly hack for broken Solaris TTYs (which send
	   <space><backspace> to slow things down) and thus gives a more pipe-
	   like behaviour (which is important if you want to transfer binary
	   content).  Note that this must be set before spawning the program.

       $object->stty(qw(mode1 mode2...))
	   Sets the tty mode for $object's associated terminal to the given
	   modes.  Note that on many systems the master side of the pty is not
	   a tty, so you have to modify the slave pty instead, see next item.
	   This needs IO::Stty installed, which is no longer required.

       $object->slave()
	   Returns a filehandle to the slave part of the pty.  Very useful in
	   modifying the terminal settings:

	     $object->slave->stty(qw(raw -echo));

	   Typical values are 'sane', 'raw', and 'raw -echo'.  Note that I
	   recommend setting the terminal to 'raw' or 'raw -echo', as this
	   avoids a lot of hassle and gives pipe-like (i.e. transparent)
	   behaviour (without the buffering issue).

       $object->print(@strings) or
       $object->send(@strings)
	   Sends the given strings to the spawned command.  Note that the
	   strings are not logged in the logfile (see print_log_file) but will
	   probably be echoed back by the pty, depending on pty settings
	   (default is echo) and thus end up there anyway.  This must also be
	   taken into account when expect()ing for an answer: the next string
	   will be the command just sent.  I suggest setting the pty to raw,
	   which disables echo and makes the pty transparently act like a
	   bidirectional pipe.

       $object->expect($timeout, @match_patterns)
	   or, more like Tcl/Expect,

	     expect($timeout,
		    '-i', [ $obj1, $obj2, ... ],
			  [ $re_pattern, sub { ...; exp_continue; }, @subparms, ],
			  [ 'eof', sub { ... } ],
			  [ 'timeout', sub { ... }, \$subparm1 ],
		    '-i', [ $objn, ...],
			  '-ex', $exact_pattern, sub { ... },
			  $exact_pattern, sub { ...; exp_continue_timeout; },
			  '-re', $re_pattern, sub { ... },
		    '-i', \@object_list, @pattern_list,
		    ...);

	   Simple interface:

	   Given $timeout in seconds Expect will wait for $object's handle to
	   produce one of the match_patterns, which are matched exactly by
	   default. If you want a regexp match, prefix the pattern with '-re'.

	   Due to o/s limitations $timeout should be a round number. If
	   $timeout is 0 Expect will check one time to see if $object's handle
	   contains any of the match_patterns. If $timeout is undef Expect
	   will wait forever for a pattern to match.

	   If called in a scalar context, expect() will return the position of
	   the matched pattern within $match_patterns, or undef if no pattern
	   was matched. This is a position starting from 1, so if you want to
	   know which of an array of @matched_patterns matched you should
	   subtract one from the return value.

	   If called in an array context expect() will return
	   ($matched_pattern_position, $error, $successfully_matching_string,
	   $before_match, and $after_match).

	   $matched_pattern_position will contain the value that would have
	   been returned if expect() had been called in a scalar context.
	   $error is the error that occurred that caused expect() to return.
	   $error will contain a number followed by a string equivalent
	   expressing the nature of the error. Possible values are undef,
	   indicating no error, '1:TIMEOUT' indicating that $timeout seconds
	   had elapsed without a match, '2:EOF' indicating an eof was read
	   from $object, '3: spawn id($fileno) died' indicating that the
	   process exited before matching and '4:$!' indicating whatever error
	   was set in $ERRNO during the last read on $object's handle or
	   during select(). All handles indicated by set_group plus STDOUT
	   will have all data to come out of $object printed to them during
	   expect() if log_group and log_stdout are set.

	   Changed from older versions is the regular expression handling. By
	   default now all strings passed to expect() are treated as literals.
	   To match a regular expression pass '-re' as a parameter in front of
	   the pattern you want to match as a regexp.

	   Example:

	     $object->expect(15, 'match me exactly','-re','match\s+me\s+exactly');

	   This change makes it possible to match literals and regular
	   expressions in the same expect() call.

	   Also new is multiline matching. ^ will now match the beginning of
	   lines. Unfortunately, because perl doesn't use $/ in determining
	   where lines break using $ to find the end of a line frequently
	   doesn't work. This is because your terminal is returning "\r\n" at
	   the end of every line. One way to check for a pattern at the end of
	   a line would be to use \r?$ instead of $.

	   Example: Spawning telnet to a host, you might look for the escape
	   character.  telnet would return to you "\r\nEscape character is
	   '^]'.\r\n". To find this you might use $match='^Escape
	   char.*\.\r?$';

	     $telnet->expect(10,'-re',$match);

	   New more Tcl/Expect-like interface:

	   It's now possible to expect on more than one connection at a time
	   by specifying '"-i"' and a single Expect object or a ref to an
	   array containing Expect objects, e.g.

	    expect($timeout,
		   '-i', $exp1, @patterns_1,
		   '-i', [ $exp2, $exp3 ], @patterns_2_3,
		  )

	   Furthermore, patterns can now be specified as array refs containing
	   [$regexp, sub { ...}, @optional_subprams] . When the pattern
	   matches, the subroutine is called with parameters
	   ($matched_expect_obj, @optional_subparms). The subroutine can
	   return the symbol `exp_continue' to continue the expect matching
	   with timeout starting anew or return the symbol
	   `exp_continue_timeout' for continuing expect without resetting the
	   timeout count.

	    $exp->expect($timeout,
			 [ qr/username: /i, sub { my $self = shift;
						  $self->send("$username\n");
						  exp_continue; }],
			 [ qr/password: /i, sub { my $self = shift;
						  $self->send("$password\n");
						  exp_continue; }],
			 $shell_prompt);

	   `expect' is now exported by default.

       $object->exp_before() or
       $object->before()
	   before() returns the 'before' part of the last expect() call. If
	   the last expect() call didn't match anything, exp_before() will
	   return the entire output of the object accumulated before the
	   expect() call finished.

	   Note that this is something different than Tcl Expects before()!!

       $object->exp_after() or
       $object->after()
	   returns the 'after' part of the last expect() call. If the last
	   expect() call didn't match anything, exp_after() will return
	   undef().

       $object->exp_match() or
       $object->match()
	   returns the string matched by the last expect() call, undef if no
	   string was matched.

       $object->exp_match_number() or
       $object->match_number()
	   exp_match_number() returns the number of the pattern matched by the
	   last expect() call. Keep in mind that the first pattern in a list
	   of patterns is 1, not 0. Returns undef if no pattern was matched.

       $object->exp_matchlist() or
       $object->matchlist()
	   exp_matchlist() returns a list of matched substrings from the
	   brackets () inside the regexp that last matched.
	   ($object->matchlist)[0] thus corresponds to $1,
	   ($object->matchlist)[1] to $2, etc.

       $object->exp_error() or
       $object->error()
	   exp_error() returns the error generated by the last expect() call
	   if no pattern was matched. It is typically useful to examine the
	   value returned by before() to find out what the output of the
	   object was in determining why it didn't match any of the patterns.

       $object->clear_accum()
	   Clear the contents of the accumulator for $object. This gets rid of
	   any residual contents of a handle after expect() or send_slow()
	   such that the next expect() call will only see new data from
	   $object. The contents of the accumulator are returned.

       $object->set_accum($value)
	   Sets the content of the accumulator for $object to $value. The
	   previous content of the accumulator is returned.

       $object->exp_command() or
       $object->command()
	   exp_command() returns the string that was used to spawn the
	   command. Helpful for debugging and for reused patternmatch
	   subroutines.

       $object->exp_exitstatus() or
       $object->exitstatus()
	   Returns the exit status of $object (if it already exited).

       $object->exp_pty_handle() or
       $object->pty_handle()
	   Returns a string representation of the attached pty, for example:
	   `spawn id(5)' (pty has fileno 5), `handle id(7)' (pty was
	   initialized from fileno 7) or `STDIN'. Useful for debugging.

       $object->restart_timeout_upon_receive(0 | 1)
	   If this is set to 1, the expect timeout is retriggered whenever
	   something is received from the spawned command.  This allows to
	   perform some aliveness testing and still expect for patterns.

	       $exp->restart_timeout_upon_receive(1);
	       $exp->expect($timeout,
			    [ timeout => \&report_timeout ],
			    [ qr/pattern/ => \&handle_pattern],
			   );

	   Now the timeout isn't triggered if the command produces any kind of
	   output, i.e. is still alive, but you can act upon patterns in the
	   output.

       $object->notransfer(1 | 0)
	   Do not truncate the content of the accumulator after a match.
	   Normally, the accumulator is set to the remains that come after the
	   matched string.  Note that this setting is per object and not per
	   pattern, so if you want to have normal acting patterns that
	   truncate the accumulator, you have to add a

	       $exp->set_accum($exp->after);

	   to their callback, e.g.

	       $exp->notransfer(1);
	       $exp->expect($timeout,
			    # accumulator not truncated, pattern1 will match again
			    [ "pattern1" => sub { my $self = shift;
						  ...
						} ],
			    # accumulator truncated, pattern2 will not match again
			    [ "pattern2" => sub { my $self = shift;
						  ...
						  $self->set_accum($self->after());
						} ],
			   );

	   This is only a temporary fix until I can rewrite the pattern
	   matching part so it can take that additional -notransfer argument.

       Expect::interconnect(@objects);
	   Read from @objects and print to their @listen_groups until an
	   escape sequence is matched from one of @objects and the associated
	   function returns 0 or undef.	 The special escape sequence 'EOF' is
	   matched when an object's handle returns an end of file. Note that
	   it is not necessary to include objects that only accept data in
	   @objects since the escape sequence is _read_ from an object.
	   Further note that the listen_group for a write-only object is
	   always empty.  Why would you want to have objects listening to
	   STDOUT (for example)?  By default every member of @objects _as well
	   as every member of its listen group_ will be set to 'raw -echo' for
	   the duration of interconnection.  Setting $object->manual_stty()
	   will stop this behavior per object.	The original tty settings will
	   be restored as interconnect exits.

	   For a generic way to interconnect processes, take a look at
	   IPC::Run.

       Expect::test_handles(@objects)
	   Given a set of objects determines which objects' handles have data
	   ready to be read. Returns an array who's members are positions in
	   @objects that have ready handles. Returns undef if there are no
	   such handles ready.

       Expect::version($version_requested or undef);
	   Returns current version of Expect. As of .99 earlier versions are
	   not supported. Too many things were changed to make versioning
	   possible.

       $object->interact( "\*FILEHANDLE, $escape_sequence")
	   interact() is essentially a macro for calling interconnect() for
	   connecting 2 processes together. \*FILEHANDLE defaults to \*STDIN
	   and $escape_sequence defaults to undef. Interaction ceases when
	   $escape_sequence is read from FILEHANDLE, not $object. $object's
	   listen group will consist solely of \*FILEHANDLE for the duration
	   of the interaction.	\*FILEHANDLE will not be echoed on STDOUT.

       $object->log_group(0 | 1 | undef)
	   Set/unset logging of $object to its 'listen group'. If set all
	   objects in the listen group will have output from $object printed
	   to them during $object->expect(), $object->send_slow(), and
	   "Expect::interconnect($object , ...)". Default value is on. During
	   creation of $object the setting will match the value of
	   $Expect::Log_Group, normally 1.

       $object->log_user(0 | 1 | undef) or
       $object->log_stdout(0 | 1 | undef)
	   Set/unset logging of object's handle to STDOUT. This corresponds to
	   Tcl's log_user variable. Returns current setting if called without
	   parameters.	Default setting is off for initialized handles.	 When
	   a process object is created (not a filehandle initialized with
	   exp_init) the log_stdout setting will match the value of
	   $Expect::Log_Stdout variable, normally 1.  If/when you initialize
	   STDIN it is usually associated with a tty which will by default
	   echo to STDOUT anyway, so be careful or you will have multiple
	   echoes.

       $object->log_file("filename" | $filehandle | \&coderef | undef)
	   Log session to a file.  All characters send to or received from the
	   spawned process are written to the file.  Normally appends to the
	   logfile, but you can pass an additional mode of "w" to truncate the
	   file upon open():

	     $object->log_file("filename", "w");

	   Returns the logfilehandle.

	   If called with an undef value, stops logging and closes logfile:

	     $object->log_file(undef);

	   If called without argument, returns the logfilehandle:

	     $fh = $object->log_file();

	   Can be set to a code ref, which will be called instead of printing
	   to the logfile:

	     $object->log_file(\&myloggerfunc);

       $object->print_log_file(@strings)
	   Prints to logfile (if opened) or calls the logfile hook function.
	   This allows the user to add arbitraty text to the logfile.  Note
	   that this could also be done as $object->log_file->print() but
	   would only work for log files, not code hooks.

       $object->set_seq($sequence, \&function, \@function_parameters)
	   During Expect->interconnect() if $sequence is read from $object
	   &function will be executed with parameters @function_parameters. It
	   is _highly recommended_ that the escape sequence be a single
	   character since the likelihood is great that the sequence will be
	   broken into to separate reads from the $object's handle, making it
	   impossible to strip $sequence from getting printed to $object's
	   listen group. \&function should be something like
	   'main::control_w_function' and @function_parameters should be an
	   array defined by the caller, passed by reference to set_seq().
	   Your function should return a non-zero value if execution of
	   interconnect() is to resume after the function returns, zero or
	   undefined if interconnect() should return after your function
	   returns.  The special sequence 'EOF' matches the end of file being
	   reached by $object.	See interconnect() for details.

       $object->set_group(@listener_objects)
	   @listener_objects is the list of objects that should have their
	   handles printed to by $object when Expect::interconnect,
	   $object->expect() or $object->send_slow() are called. Calling w/out
	   parameters will return the current list of the listener objects.

       $object->manual_stty(0 | 1 | undef)
	   Sets/unsets whether or not Expect should make reasonable guesses as
	   to when and how to set tty parameters for $object. Will match
	   $Expect::Manual_Stty value (normally 0) when $object is created. If
	   called without parameters manual_stty() will return the current
	   manual_stty setting.

       $object->match_max($maximum_buffer_length | undef) or
       $object->max_accum($maximum_buffer_length | undef)
	   Set the maximum accumulator size for object. This is useful if you
	   think that the accumulator will grow out of hand during expect()
	   calls. Since the buffer will be matched by every match_pattern it
	   may get slow if the buffer gets too large. Returns current value if
	   called without parameters.  Not defined by default.

       $object->notransfer(0 | 1)
	   If set, matched strings will not be deleted from the accumulator.
	   Returns current value if called without parameters.	False by
	   default.

       $object->exp_pid() or
       $object->pid()
	   Return pid of $object, if one exists. Initialized filehandles will
	   not have pids (of course).

       $object->send_slow($delay, @strings);
	   print each character from each string of @strings one at a time
	   with $delay seconds before each character. This is handy for
	   devices such as modems that can be annoying if you send them data
	   too fast. After each character $object will be checked to determine
	   whether or not it has any new data ready and if so update the
	   accumulator for future expect() calls and print the output to
	   STDOUT and @listen_group if log_stdout and log_group are
	   appropriately set.

   Configurable Package Variables:
       $Expect::Debug
	   Defaults to 0. Newly created objects have a $object->debug() value
	   of $Expect::Debug. See $object->debug();

       $Expect::Do_Soft_Close
	   Defaults to 0. When destroying objects, soft_close may take up to
	   half a minute to shut everything down.  From now on, only
	   hard_close will be called, which is less polite but still gives the
	   process a chance to terminate properly.  Set this to '1' for old
	   behaviour.

       $Expect::Exp_Internal
	   Defaults to 0. Newly created objects have a $object->exp_internal()
	   value of $Expect::Exp_Internal. See $object->exp_internal().

       $Expect::IgnoreEintr
	   Defaults to 0. If set to 1, when waiting for new data, Expect will
	   ignore EINTR errors and restart the select() call instead.

       $Expect::Log_Group
	   Defaults to 1. Newly created objects have a $object->log_group()
	   value of $Expect::Log_Group. See $object->log_group().

       $Expect::Log_Stdout
	   Defaults to 1 for spawned commands, 0 for file handles attached
	   with exp_init(). Newly created objects have a $object->log_stdout()
	   value of $Expect::Log_Stdout. See $object->log_stdout().

       $Expect::Manual_Stty
	   Defaults to 0. Newly created objects have a $object->manual_stty()
	   value of $Expect::Manual_Stty. See $object->manual_stty().

       $Expect::Multiline_Matching
		   Defaults to 1. Affects whether or not expect() uses the /m flag for
	   doing regular expression matching. If set to 1 /m is used.
		   This makes a difference when you are trying to match ^ and $. If
	   you have this on you can match lines in the middle of a page of output
	   using ^ and $ instead of it matching the beginning and end of the entire
	   expression. I think this is handy.

CONTRIBUTIONS
       Lee Eakin <leakin@japh.itg.ti.com> has ported the kibitz script from
       Tcl/Expect to Perl/Expect.

       Jeff Carr <jcarr@linuxmachines.com> provided a simple example of how
       handle terminal window resize events (transmitted via the WINCH signal)
       in a ssh session.

       You can find both scripts in the examples/ subdir.  Thanks to both!

       Historical notes:

       There are still a few lines of code dating back to the inspirational
       Comm.pl and Chat.pl modules without which this would not have been
       possible.  Kudos to Eric Arnold <Eric.Arnold@Sun.com> and Randal 'Nuke
       your NT box with one line of perl code' Schwartz<merlyn@stonehenge.com>
       for making these available to the perl public.

       As of .98 I think all the old code is toast. No way could this have
       been done without it though. Special thanks to Graham Barr for helping
       make sense of the IO::Handle stuff as well as providing the highly
       recommended IO::Tty module.

REFERENCES
       Mark Rogaski <rogaski@att.com> wrote:

       "I figured that you'd like to know that Expect.pm has been very useful
       to AT&T Labs over the past couple of years (since I first talked to
       Austin about design decisions). We use Expect.pm for managing the
       switches in our network via the telnet interface, and such automation
       has significantly increased our reliability. So, you can honestly say
       that one of the largest digital networks in existence (AT&T Frame
       Relay) uses Expect.pm quite extensively."

FAQ - Frequently Asked Questions
       This is a growing collection of things that might help.	Please send
       you questions that are not answered here to RGiersig@cpan.org

   What systems does Expect run on?
       Expect itself doesn't have real system dependencies, but the underlying
       IO::Tty needs pseudoterminals. IO::Stty uses POSIX.pm and Fcntl.pm.

       I have used it on Solaris, Linux and AIX, others report *BSD and OSF as
       working.	 Generally, any modern POSIX Unix should do, but there are
       exceptions to every rule.  Feedback is appreciated.

       See IO::Tty for a list of verified systems.

   Can I use this module with ActivePerl on Windows?
       Up to now, the answer was 'No', but this has changed.

       You still cannot use ActivePerl, but if you use the Cygwin environment
       (http://sources.redhat.com), which brings its own perl, and have the
       latest IO::Tty (v0.05 or later) installed, it should work (feedback
       appreciated).

   The examples in the tutorial don't work!
       The tutorial is hopelessly out of date and needs a serious overhaul.  I
       appologize for this, I have concentrated my efforts mainly on the
       functionality.  Volunteers welcomed.

   How can I find out what Expect is doing?
       If you set

	 $Expect::Exp_Internal = 1;

       Expect will tell you very verbosely what it is receiving and sending,
       what matching it is trying and what it found.  You can do this on a
       per-command base with

	 $exp->exp_internal(1);

       You can also set

	 $Expect::Debug = 1;  # or 2, 3 for more verbose output

       or

	 $exp->debug(1);

       which gives you even more output.

   I am seeing the output of the command I spawned.  Can I turn that off?
       Yes, just set

	 $Expect::Log_Stdout = 0;

       to globally disable it or

	  $exp->log_stdout(0);

       for just that command.  'log_user' is provided as an alias so
       Tcl/Expect user get a DWIM experience... :-)

   No, I mean that when I send some text to the spawned process, it gets
       echoed back and I have to deal with it in the next expect.
       This is caused by the pty, which has probably 'echo' enabled.  A
       solution would be to set the pty to raw mode, which in general is
       cleaner for communication between two programs (no more unexpected
       character translations).	 Unfortunately this would break a lot of old
       code that sends "\r" to the program instead of "\n" (translating this
       is also handled by the pty), so I won't add this to Expect just like
       that.  But feel free to experiment with "$exp->raw_pty(1)".

   How do I send control characters to a process?
       A: You can send any characters to a process with the print command. To
       represent a control character in Perl, use \c followed by the letter.
       For example, control-G can be represented with "\cG" . Note that this
       will not work if you single-quote your string. So, to send control-C to
       a process in $exp, do:

	 print $exp "\cC";

       Or, if you prefer:

	 $exp->send("\cC");

       The ability to include control characters in a string like this is
       provided by Perl, not by Expect.pm . Trying to learn Expect.pm without
       a thorough grounding in Perl can be very daunting. We suggest you look
       into some of the excellent Perl learning material, such as the books
       _Programming Perl_ and _Learning Perl_ by O'Reilly, as well as the
       extensive online Perl documentation available through the perldoc
       command.

   My script fails from time to time without any obvious reason.  It seems
       that I am sometimes loosing output from the spawned program.
       You could be exiting too fast without giving the spawned program enough
       time to finish.	Try adding $exp->soft_close() to terminate the program
       gracefully or do an expect() for 'eof'.

       Alternatively, try adding a 'sleep 1' after you spawn() the program.
       It could be that pty creation on your system is just slow (but this is
       rather improbable if you are using the latest IO-Tty).

   I want to automate password entry for su/ssh/scp/rsh/...
       You shouldn't use Expect for this.  Putting passwords, especially root
       passwords, into scripts in clear text can mean severe security
       problems.  I strongly recommend using other means.  For 'su', consider
       switching to 'sudo', which gives you root access on a per-command and
       per-user basis without the need to enter passwords.  'ssh'/'scp' can be
       set up with RSA authentication without passwords.  'rsh' can use the
       .rhost mechanism, but I'd strongly suggest to switch to 'ssh'; to
       mention 'rsh' and 'security' in the same sentence makes an oxymoron.

       It will work for 'telnet', though, and there are valid uses for it, but
       you still might want to consider using 'ssh', as keeping cleartext
       passwords around is very insecure.

   I want to use Expect to automate [anything with a buzzword]...
       Are you sure there is no other, easier way?  As a rule of thumb, Expect
       is useful for automating things that expect to talk to a human, where
       no formal standard applies.  For other tasks that do follow a well-
       defined protocol, there are often better-suited modules that already
       can handle those protocols.  Don't try to do HTTP requests by spawning
       telnet to port 80, use LWP instead.  To automate FTP, take a look at
       Net::FTP or "ncftp" (http://www.ncftp.org).  You don't use a
       screwdriver to hammer in your nails either, or do you?

   Is it possible to use threads with Expect?
       Basically yes, with one restriction: you must spawn() your programs in
       the main thread and then pass the Expect objects to the handling
       threads. The reason is that spawn() uses fork(), and perlthrtut:

	 "Thinking of mixing fork() and threads?  Please lie down and wait until the feeling passes."

   I want to log the whole session to a file.
       Use

	 $exp->log_file("filename");

       or

	 $exp->log_file($filehandle);

       or even

	 $exp->log_file(\&log_procedure);

       for maximum flexibility.

       Note that the logfile is appended to by default, but you can specify an
       optional mode "w" to truncate the logfile:

	 $exp->log_file("filename", "w");

       To stop logging, just call it with a false argument:

	 $exp->log_file(undef);

   How can I turn off multi-line matching for my regexps?
       To globally unset multi-line matching for all regexps:

	 $Expect::Multiline_Matching = 0;

       You can do that on a per-regexp basis by stating "(?-m)" inside the
       regexp (you need perl5.00503 or later for that).

   How can I expect on multiple spawned commands?
       You can use the -i parameter to specify a single object or a list of
       Expect objects.	All following patterns will be evaluated against that
       list.

       You can specify -i multiple times to create groups of objects and
       patterns to match against within the same expect statement.

       This works just like in Tcl/Expect.

       See the source example below.

   I seem to have problems with ptys!
       Well, pty handling is really a black magic, as it is extremely system
       dependend.  I have extensively revised IO-Tty, so these problems should
       be gone.

       If your system is listed in the "verified" list of IO::Tty, you
       probably have some non-standard setup, e.g. you compiled your Linux-
       kernel yourself and disabled ptys.  Please ask your friendly sysadmin
       for help.

       If your system is not listed, unpack the latest version of IO::Tty, do
       a 'perl Makefile.PL; make; make test; uname "-a"' and send me the
       results and I'll see what I can deduce from that.

   I just want to read the output of a process without expect()ing anything.
       How can I do this?
       [ Are you sure you need Expect for this?	 How about qx() or
       open("prog|")? ]

       By using expect without any patterns to match.

	 $process->expect(undef); # Forever until EOF
	 $process->expect($timeout); # For a few seconds
	 $process->expect(0); # Is there anything ready on the handle now?

   Ok, so now how do I get what was read on the handle?
	 $read = $process->before();

   Where's IO::Pty?
       Find it on CPAN as IO-Tty, which provides both.

   How come when I automate the passwd program to change passwords for me
       passwd dies before changing the password sometimes/every time?
       What's happening is you are closing the handle before passwd exits.
       When you close the handle to a process, it is sent a signal (SIGPIPE?)
       telling it that STDOUT has gone away. The default behavior for
       processes is to die in this circumstance. Two ways you can make this
       not happen are:

	 $process->soft_close();

       This will wait 15 seconds for a process to come up with an EOF by
       itself before killing it.

	 $process->expect(undef);

       This will wait forever for the process to match an empty set of
       patterns. It will return when the process hits an EOF.

       As a rule, you should always expect() the result of your transaction
       before you continue with processing.

   How come when I try to make a logfile with log_file() or set_group() it
       doesn't print anything after the last time I run expect()?
       Output is only printed to the logfile/group when Expect reads from the
       process, during expect(), send_slow() and interconnect().  One way you
       can force this is to make use of

	 $process->expect(undef);

       and

	 $process->expect(0);

       which will make expect() run with an empty pattern set forever or just
       for an instant to capture the output of $process. The output is
       available in the accumulator, so you can grab it using
       $process->before().

   I seem to have problems with terminal settings, double echoing, etc.
       Tty settings are a major pain to keep track of. If you find unexpected
       behavior such as double-echoing or a frozen session, doublecheck the
       documentation for default settings. When in doubt, handle them yourself
       using $exp->stty() and manual_stty() functions.	As of .98 you
       shouldn't have to worry about stty settings getting fouled unless you
       use interconnect or intentionally change them (like doing -echo to get
       a password).

       If you foul up your terminal's tty settings, kill any hung processes
       and enter 'stty sane' at a shell prompt. This should make your terminal
       manageable again.

       Note that IO::Tty returns ptys with your systems default setting
       regarding echoing, CRLF translation etc. and Expect does not change
       them.  I have considered setting the ptys to 'raw' without any
       translation whatsoever, but this would break a lot of existing things,
       as '\r' translation would not work anymore.  On the other hand, a raw
       pty works much like a pipe and is more WYGIWYE (what you get is what
       you expect), so I suggest you set it to 'raw' by yourself:

	 $exp = new Expect;
	 $exp->raw_pty(1);
	 $exp->spawn(...);

       To disable echo:

	 $exp->slave->stty(qw(-echo));

   I'm spawning a telnet/ssh session and then let the user interact with it.
       But screen-oriented applications on the other side don't work properly.
       You have to set the terminal screen size for that.  Luckily, IO::Pty
       already has a method for that, so modify your code to look like this:

	 my $exp = new Expect;
	 $exp->slave->clone_winsize_from(\*STDIN);
	 $exp->spawn("telnet somehost);

       Also, some applications need the TERM shell variable set so they know
       how to move the cursor across the screen.  When logging in, the remote
       shell sends a query (Ctrl-Z I think) and expects the terminal to answer
       with a string, e.g. 'xterm'.  If you really want to go that way (be
       aware, madness lies at its end), you can handle that and send back the
       value in $ENV{TERM}.  This is only a hand-waving explanation, please
       figure out the details by yourself.

   I set the terminal size as explained above, but if I resize the window, the
       application does not notice this.
       You have to catch the signal WINCH ("window size changed"), change the
       terminal size and propagate the signal to the spawned application:

	 my $exp = new Expect;
	 $exp->slave->clone_winsize_from(\*STDIN);
	 $exp->spawn("ssh somehost);
	 $SIG{WINCH} = \&winch;

	 sub winch {
	   $exp->slave->clone_winsize_from(\*STDIN);
	   kill WINCH => $exp->pid if $exp->pid;
	   $SIG{WINCH} = \&winch;
	 }

	 $exp->interact();

       There is an example file ssh.pl in the examples/ subdir that shows how
       this works with ssh. Please note that I do strongly object against
       using Expect to automate ssh login, as there are better way to do that
       (see ssh-keygen).

   I noticed that the test uses a string that resembles, but not exactly
       matches, a well-known sentence that contains every character.  What
       does that mean?
       That means you are anal-retentive. :-)  [Gotcha there!]

   I get a "Could not assign a pty" error when running as a non-root user on
       an IRIX box?
       The OS may not be configured to grant additional pty's (pseudo
       terminals) to non-root users.  /usr/sbin/mkpts should be 4755, not 700
       for this to work.  I don't know about security implications if you do
       this.

   How come I don't notice when the spawned process closes its stdin/out/err??
       You are probably on one of the systems where the master doesn't get an
       EOF when the slave closes stdin/out/err.

       One possible solution is when you spawn a process, follow it with a
       unique string that would indicate the process is finished.

	 $process = Expect->spawn('telnet somehost; echo ____END____');

       And then $process->expect($timeout,'____END____','other','patterns');

Source Examples
   How to automate login
	 my $telnet = new Net::Telnet ("remotehost") # see Net::Telnet
	   or die "Cannot telnet to remotehost: $!\n";;
	 my $exp = Expect->exp_init($telnet);

	 # deprecated use of spawned telnet command
	 # my $exp = Expect->spawn("telnet localhost")
	 #   or die "Cannot spawn telnet: $!\n";;

	 my $spawn_ok;
	 $exp->expect($timeout,
		      [
		       qr'login: $',
		       sub {
			 $spawn_ok = 1;
			 my $fh = shift;
			 $fh->send("$username\n");
			 exp_continue;
		       }
		      ],
		      [
		       'Password: $',
		       sub {
			 my $fh = shift;
			 print $fh "$password\n";
			 exp_continue;
		       }
		      ],
		      [
		       eof =>
		       sub {
			 if ($spawn_ok) {
			   die "ERROR: premature EOF in login.\n";
			 } else {
			   die "ERROR: could not spawn telnet.\n";
			 }
		       }
		      ],
		      [
		       timeout =>
		       sub {
			 die "No login.\n";
		       }
		      ],
		      '-re', qr'[#>:] $', #' wait for shell prompt, then exit expect
		     );

   How to expect on multiple spawned commands
	 foreach my $cmd (@list_of_commands) {
	   push @commands, Expect->spawn($cmd);
	 }

	 expect($timeout,
		'-i', \@commands,
		[
		 qr"pattern",	       # find this pattern in output of all commands
		 sub {
		   my $obj = shift;    # object that matched
		   print $obj "something\n";
		   exp_continue;       # we don't want to terminate the expect call
		 }
		],
		'-i', $some_other_command,
		[
		 "some other pattern",
		 sub {
		   my ($obj, $parmref) = @_;
		   # ...

		   # now we exit the expect command
		 },
		 \$parm
		],
	       );

   How to propagate terminal sizes
	 my $exp = new Expect;
	 $exp->slave->clone_winsize_from(\*STDIN);
	 $exp->spawn("ssh somehost);
	 $SIG{WINCH} = \&winch;

	 sub winch {
	   $exp->slave->clone_winsize_from(\*STDIN);
	   kill WINCH => $exp->pid if $exp->pid;
	   $SIG{WINCH} = \&winch;
	 }

	 $exp->interact();

HOMEPAGE
       http://sourceforge.net/projects/expectperl/

MAILING LISTS
       There are two mailing lists available, expectperl-announce and
       expectperl-discuss, at

	 http://lists.sourceforge.net/lists/listinfo/expectperl-announce

       and

	 http://lists.sourceforge.net/lists/listinfo/expectperl-discuss

BUG TRACKING
       You can use the CPAN Request Tracker http://rt.cpan.org/ and submit new
       bugs under

	 http://rt.cpan.org/Ticket/Create.html?Queue=Expect

AUTHORS
       (c) 1997 Austin Schutz <ASchutz@users.sourceforge.net> (retired)

       expect() interface & functionality enhancements (c) 1999-2006 Roland
       Giersig.

       This module is now maintained by Roland Giersig <RGiersig@cpan.org>

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

DISCLAIMER
       THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
       WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
       MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
       IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT,
       INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
       BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
       OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
       ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
       TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
       USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
       DAMAGE.

       In other words: Use at your own risk.  Provided as is.  Your mileage
       may vary.  Read the source, Luke!

       And finally, just to be sure:

       Any Use of This Product, in Any Manner Whatsoever, Will Increase the
       Amount of Disorder in the Universe. Although No Liability Is Implied
       Herein, the Consumer Is Warned That This Process Will Ultimately Lead
       to the Heat Death of the Universe.

POD ERRORS
       Hey! The above document had some coding errors, which are explained
       below:

       Around line 653:
	   '=item' outside of any '=over'

       Around line 702:
	   You forgot a '=back' before '=head1'

perl v5.16.2			  2007-07-19			     Expect(3)
[top]

List of man pages available for MacOSX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net