DOWNLOAD

	http://www.cpan.org/authors/id/S/ST/STEVEGT/IPC-Session-0.03.tar.gz

NAME
    IPC::Session - remote shell persistent session object; encapsulates
    open3()

SYNOPSIS
     use IPC::Session;

     # open ssh session to fred
     # -- set timeout of 30 seconds for all send() calls
     my $session = new IPC::Session("ssh fred",30);
     
     $session->send("hostname");  # run `hostname` command on fred
     print $session->stdout();  # prints "fred"
     $session->send("date");  # run `date` within same ssh
     print $session->stdout();  # prints date
     
     # use like 'expect':
     $session->send("uname -s");
     for ($session->stdout)
     {
            /IRIX/ && do { $netstat = "/usr/etc/netstat" };
            /ConvexOS/ && do { $netstat = "/usr/ucb/netstat" };
            /Linux/ && do { $netstat = "/bin/netstat" };
     }
     
     # errno returned in scalar context:
     $errno = $session->send("$netstat -rn");
     # try this:
     $session->send("grep '^$user:' /etc/passwd") 
             && warn "$user not there";
     
     # hash returned in array context:
     %netstat = $session->send("$netstat -in");
     print "$netstat{'stdout'}\n";  # prints interface table
     print "$netstat{'stderr'}\n";  # prints nothing (hopefully)
     print "$netstat{'errno'}\n";   # prints 0

DESCRIPTION
    This module encapsulates the open3() function call (see the IPC::Open3
    manpage) and its associated filehandles, making it easy to maintain
    multiple persistent 'ssh' and/or 'rsh' sessions within the same perl
    script.

    The remote shell session is kept open for the life of the object; this
    avoids the overhead of repeatedly opening remote shells via multiple ssh
    or rsh calls. This persistence is particularly useful if you are using
    ssh for your remote shell invocation; it helps you overcome the high ssh
    startup time.

    For applications requiring remote command invocation, this module
    provides functionality that is similar to 'expect' or Expect.pm, but in
    a lightweight more Perlish package, with discrete STDOUT, STDERR, and
    return code processing.

METHODS
  my $session = new IPC::Session("ssh fred",30);

    The constructor accepts the command string to be used to open the remote
    shell session, such as ssh or rsh; it also accepts an optional timeout
    value, in seconds. It returns a reference to the unique session object.

    If the timeout is not specified then it defaults to 60 seconds. The
    timeout value can also be changed later; see the section on "timeout()".

  $commandhandle = $session->send("hostname");

    The send() method accepts a command string to be executed on the remote
    host. The command will be executed in the context of the default shell
    of the remote user (unless you start a different shell by sending the
    appropriate command...). All shell escapes, command line terminators,
    pipes, redirectors, etc. are legal and should work, though you of course
    will have to escape special characters that have meaning to Perl.

    In a scalar context, this method returns the return code produced by the
    command string.

    In an array context, this method returns a hash containing the return
    code as well as the full text of the command string's output from the
    STDOUT and STDERR file handles. The hash keys are 'stdout', 'stderr',
    and 'errno'.

  print $session->stdout();

    Returns the full STDOUT text generated from the last send() command
    string.

    Also available via array context return codes -- see the section on
    "send()".

  print $session->stderr();

    Returns the full STDERR text generated from the last send() command
    string.

    Also available via array context return codes -- see the section on
    "send()".

  print $session->errno();

    Returns the return code generated from the last send() command string.

    Also available via array context return codes -- see the section on
    "send()".

  $session->timeout(90);

    Allows you to change the timeout for subsequent send() calls.

    The timeout value is in seconds. Fractional seconds are allowed. The
    timeout applies to all send() calls.

    Returns the current timeout. Can be called with no args.

BUGS/RESTRICTIONS
    *   The remote shell command you specify in new() is assumed to not prompt
        for any passwords or present any challenge codes; i.e.; you must use
        .rhosts or the equivalent. This restriction may be removed in future
        versions of this module, but it's there now.

AUTHOR
     Steve Traugott <stevegt@TerraLuna.Org>

SEE ALSO
    the IPC::Open3 manpage, the rsh(1) manpage, the ssh(1) manpage, the
    Expect manpage, the expect(1) manpage