Linux.pl
Opcje wyszukiwania podręcznika man:
Lista stron man zaczynających się od znaku:
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z   ALPHA   NUM   OTHER   ALL
Net::Telnet(3pm)      User Contributed Perl Documentation     Net::Telnet(3pm)

NAME
       Net::Telnet - interact with TELNET port or other TCP ports

SYNOPSIS
       "use Net::Telnet ();"

       see METHODS section below

DESCRIPTION
       Net::Telnet allows you to make client connections to a TCP port and do
       network I/O, especially to a port using the TELNET protocol.  Simple
       I/O methods such as print, get, and getline are provided.  More sophis-
       ticated interactive features are provided because connecting to a TEL-
       NET port ultimately means communicating with a program designed for
       human interaction.  These interactive features include the ability to
       specify a time-out and to wait for patterns to appear in the input
       stream, such as the prompt from a shell.

       Other reasons to use this module than strictly with a TELNET port are:

       o You're not familiar with sockets and you want a simple way to make
         client connections to TCP services.

       o You want to be able to specify your own time-out while connecting,
         reading, or writing.

       o You're communicating with an interactive program at the other end of
         some socket or pipe and you want to wait for certain patterns to
         appear.

       Here's an example that prints who's logged-on to the remote host
       sparky.  In addition to a username and password, you must also know the
       user's shell prompt, which for this example is "bash$"

           use Net::Telnet ();
           $t = new Net::Telnet (Timeout => 10,
                                 Prompt => '/bash\$ $/');
           $t->open("sparky");
           $t->login($username, $passwd);
           @lines = $t->cmd("who");
           print @lines;

       More examples are in the EXAMPLES section below.

       Usage questions should be directed to the Usenet newsgroup
       comp.lang.perl.modules.

       Contact me, Jay Rogers <jay@rgrs.com>, if you find any bugs or have
       suggestions for improvement.

       What To Know Before Using

       o All output is flushed while all input is buffered.  Each object con-
         tains its own input buffer.

       o The output record separator for "print()" and "cmd()" is set to "\n"
         by default, so that you don't have to append all your commands with a
         newline.  To avoid printing a trailing "\n" use "put()" or set the
         output_record_separator to "".

       o The methods "login()" and "cmd()" use the prompt setting in the
         object to determine when a login or remote command is complete.
         Those methods will fail with a time-out if you don't set the prompt
         correctly.

       o Use a combination of "print()" and "waitfor()" as an alternative to
         "login()" or "cmd()" when they don't do what you want.

       o Errors such as timing-out are handled according to the error mode
         action.  The default action is to print an error message to standard
         error and have the program die.  See the "errmode()" method for more
         information.

       o When constructing the match operator argument for "prompt()" or
         "waitfor()", always use single quotes instead of double quotes to
         avoid unexpected backslash interpretation (e.g. '/bash\$ $/').  If
         you're constructing a DOS like file path, you'll need to use four
         backslashes to represent one (e.g. '/c:\\\\users\\\\bill>$/i').

         Of course don't forget about regexp metacharacters like ".", "[", or
         "$".  You'll only need a single backslash to quote them.  The anchor
         metacharacters "^" and "$" refer to positions in the input buffer.
         To avoid matching characters read that look like a prompt, it's a
         good idea to end your prompt pattern with the "$" anchor.  That way
         the prompt will only match if it's the last thing read.

       o In the input stream, each sequence of carriage return and line feed
         (i.e. "\015\012" or CR LF) is converted to "\n".  In the output
         stream, each occurrence of "\n" is converted to a sequence of CR LF.
         See "binmode()" to change the behavior.  TCP protocols typically use
         the ASCII sequence, carriage return and line feed to designate a new-
         line.

       o Timing-out while making a connection is disabled for machines that
         don't support the "alarm()" function.  Most notably these include MS-
         Windows machines.

       o You'll need to be running at least Perl version 5.002 to use this
         module.  This module does not require any libraries that don't
         already come with a standard Perl distribution.

         If you have the IO:: libraries installed (they come standard with
         perl5.004 and later) then IO::Socket::INET is used as a base class,
         otherwise FileHandle is used.

       o Contact me, Jay Rogers <jay@rgrs.com>, if you find any bugs or have
         suggestions for improvement.

       Debugging

       The typical usage bug causes a time-out error because you've made
       incorrect assumptions about what the remote side actually sends.  The
       easiest way to reconcile what the remote side sends with your expecta-
       tions is to use "input_log()" or "dump_log()".

       "dump_log()" allows you to see the data being sent from the remote side
       before any translation is done, while "input_log()" shows you the
       results after translation.  The translation includes converting end of
       line characters, removing and responding to TELNET protocol commands in
       the data stream.

       Style of Named Parameters

       Two different styles of named parameters are supported.  This document
       only shows the IO:: style:

           Net::Telnet->new(Timeout => 20);

       however the dash-option style is also allowed:

           Net::Telnet->new(-timeout => 20);

       Connecting to a Remote MS-Windows Machine

       By default MS-Windows doesn't come with a TELNET server.  However third
       party TELNET servers are available.  Unfortunately many of these
       servers falsely claim to be a TELNET server.  This is especially true
       of the so-called "Microsoft Telnet Server" that comes installed with
       some newer versions MS-Windows.

       When a TELNET server first accepts a connection, it must use the ASCII
       control characters carriage-return and line-feed to start a new line
       (see RFC854).  A server like the "Microsoft Telnet Server" that doesn't
       do this, isn't a TELNET server.  These servers send ANSI terminal
       escape sequences to position to a column on a subsequent line and to
       even position while writing characters that are adjacent to each other.
       Worse, when sending output these servers resend previously sent command
       output in a misguided attempt to display an entire terminal screen.

       Connecting Net::Telnet to one of these false TELNET servers makes your
       job of parsing command output very difficult.  It's better to replace a
       false TELNET server with a real TELNET server.  The better TELNET
       servers for MS-Windows allow you to avoid the ANSI escapes by turning
       off something some of them call console mode.

METHODS
       In the calling sequences below, square brackets [] represent optional
       parameters.

       new - create a new Net::Telnet object
               $obj = new Net::Telnet ([$host]);

               $obj = new Net::Telnet ([Binmode    => $mode,]
                                       [Cmd_remove_mode => $mode,]
                                       [Dump_Log   => $filename,]
                                       [Errmode    => $errmode,]
                                       [Fhopen     => $filehandle,]
                                       [Host       => $host,]
                                       [Input_log  => $file,]
                                       [Input_record_separator => $chars,]
                                       [Option_log => $file,]
                                       [Ors        => $chars,]
                                       [Output_log => $file,]
                                       [Output_record_separator => $chars,]
                                       [Port       => $port,]
                                       [Prompt     => $matchop,]
                                       [Rs         => $chars,]
                                       [Telnetmode => $mode,]
                                       [Timeout    => $secs,]);

           This is the constructor for Net::Telnet objects.  A new object is
           returned on success, the error mode action is performed on failure
           - see "errmode()".  The optional arguments are short-cuts to meth-
           ods of the same name.

           If the $host argument is given then the object is opened by con-
           necting to TCP $port on $host.  Also see "open()".  The new object
           returned is given the following defaults in the absence of corre-
           sponding named parameters:

           *   The default Host is "localhost"

           *   The default Port is 23

           *   The default Prompt is '/[\$%#>] $/'

           *   The default Timeout is 10

           *   The default Errmode is "die"

           *   The default Output_record_separator is "\n".  Note that Ors is
               synonymous with Output_record_separator.

           *   The default Input_record_separator is "\n".  Note that Rs is
               synonymous with Input_record_separator.

           *   The default Binmode is 0, which means do newline translation.

           *   The default Telnetmode is 1, which means respond to TELNET com-
               mands in the data stream.

           *   The default Cmd_remove_mode is "auto"

           *   The defaults for Dump_log, Input_log, Option_log, and Out-
               put_log are "", which means that logging is turned-off.

       binmode - toggle newline translation
               $mode = $obj->binmode;

               $prev = $obj->binmode($mode);

           This method controls whether or not sequences of carriage returns
           and line feeds (CR LF or more specifically "\015\012") are trans-
           lated.  By default they are translated (i.e. binmode is 0).

           If no argument is given, the current mode is returned.

           If $mode is 1 then binmode is on and newline translation is not
           done.

           If $mode is 0 then binmode is off and newline translation is done.
           In the input stream, each sequence of CR LF is converted to "\n"
           and in the output stream, each occurrence of "\n" is converted to a
           sequence of CR LF.

           Note that input is always buffered.  Changing binmode doesn't
           effect what's already been read into the buffer.  Output is not
           buffered and changing binmode will have an immediate effect.

       break - send TELNET break character
               $ok = $obj->break;

           This method sends the TELNET break character.  This character is
           provided because it's a signal outside the ASCII character set
           which is currently given local meaning within many systems.  It's
           intended to indicate that the Break Key or the Attention Key was
           hit.

           This method returns 1 on success, or performs the error mode action
           on failure.

       buffer - scalar reference to object's input buffer
               $ref = $obj->buffer;

           This method returns a scalar reference to the input buffer for
           $obj.  Data in the input buffer is data that has been read from the
           remote side but has yet to be read by the user.  Modifications to
           the input buffer are returned by a subsequent read.

       buffer_empty - discard all data in object's input buffer
               $obj->buffer_empty;

           This method removes all data in the input buffer for $obj.

       close - close object
               $ok = $obj->close;

           This method closes the socket, file, or pipe associated with the
           object.  It always returns a value of 1.

       cmd - issue command and retrieve output
               $ok = $obj->cmd($string);
               $ok = $obj->cmd(String   => $string,
                               [Output  => $ref,]
                               [Cmd_remove_mode => $mode,]
                               [Errmode => $mode,]
                               [Input_record_separator => $chars,]
                               [Ors     => $chars,]
                               [Output_record_separator => $chars,]
                               [Prompt  => $match,]
                               [Rs      => $chars,]
                               [Timeout => $secs,]);

               @output = $obj->cmd($string);
               @output = $obj->cmd(String   => $string,
                                   [Output  => $ref,]
                                   [Cmd_remove_mode => $mode,]
                                   [Errmode => $mode,]
                                   [Input_record_separator => $chars,]
                                   [Ors     => $chars,]
                                   [Output_record_separator => $chars,]
                                   [Prompt  => $match,]
                                   [Rs      => $chars,]
                                   [Timeout => $secs,]);

           This method sends the command $string, and reads the characters
           sent back by the command up until and including the matching
           prompt.  It's assumed that the program to which you're sending is
           some kind of command prompting interpreter such as a shell.

           The command $string is automatically appended with the out-
           put_record_separator, By default that's "\n".  This is similar to
           someone typing a command and hitting the return key.  Set the out-
           put_record_separator to change this behavior.

           In a scalar context, the characters read from the remote side are
           discarded and 1 is returned on success.  On time-out, eof, or other
           failures, the error mode action is performed.  See "errmode()".

           In a list context, just the output generated by the command is
           returned, one line per element.  In other words, all the characters
           in between the echoed back command string and the prompt are
           returned.  If the command happens to return no output, a list con-
           taining one element, the empty string is returned.  This is so the
           list will indicate true in a boolean context.  On time-out, eof, or
           other failures, the error mode action is performed.  See
           "errmode()".

           The characters that matched the prompt may be retrieved using
           "last_prompt()".

           Many command interpreters echo back the command sent.  In most sit-
           uations, this method removes the first line returned from the
           remote side (i.e. the echoed back command).  See
           "cmd_remove_mode()" for more control over this feature.

           Use "dump_log()" to debug when this method keeps timing-out and you
           don't think it should.

           Consider using a combination of "print()" and "waitfor()" as an
           alternative to this method when it doesn't do what you want, e.g.
           the command you send prompts for input.

           The Output named parameter provides an alternative method of
           receiving command output.  If you pass a scalar reference, all the
           output (even if it contains multiple lines) is returned in the ref-
           erenced scalar.  If you pass an array or hash reference, the lines
           of output are returned in the referenced array or hash.  You can
           use "input_record_separator()" to change the notion of what sepa-
           rates a line.

           Optional named parameters are provided to override the current set-
           tings of cmd_remove_mode, errmode, input_record_separator, ors,
           output_record_separator, prompt, rs, and timeout.  Rs is synonymous
           with input_record_separator and ors is synonymous with out-
           put_record_separator.

       cmd_remove_mode - toggle removal of echoed commands
               $mode = $obj->cmd_remove_mode;

               $prev = $obj->cmd_remove_mode($mode);

           This method controls how to deal with echoed back commands in the
           output returned by cmd().  Typically, when you send a command to
           the remote side, the first line of output returned is the command
           echoed back.  Use this mode to remove the first line of output nor-
           mally returned by cmd().

           If no argument is given, the current mode is returned.

           If $mode is 0 then the command output returned from cmd() has no
           lines removed.  If $mode is a positive integer, then the first
           $mode lines of command output are stripped.

           By default, $mode is set to "auto".  Auto means that whether or not
           the first line of command output is stripped, depends on whether or
           not the remote side offered to echo.  By default, Net::Telnet
           always accepts an offer to echo by the remote side.  You can change
           the default to reject such an offer using "option_accept()".

           A warning is printed to STDERR when attempting to set this
           attribute to something that's not "auto" or a non-negative integer.

       dump_log - log all I/O in dump format
               $fh = $obj->dump_log;

               $fh = $obj->dump_log($fh);

               $fh = $obj->dump_log($filename);

           This method starts or stops dump format logging of all the object's
           input and output.  The dump format shows the blocks read and writ-
           ten in a hexadecimal and printable character format.  This method
           is useful when debugging, however you might want to first try
           "input_log()" as it's more readable.

           If no argument is given, the current log filehandle is returned.
           An empty string indicates logging is off.

           To stop logging, use an empty string as an argument.

           If an open filehandle is given, it is used for logging and
           returned.  Otherwise, the argument is assumed to be the name of a
           file, the file is opened and a filehandle to it is returned.  If
           the file can't be opened for writing, the error mode action is per-
           formed.

       eof - end of file indicator
               $eof = $obj->eof;

           This method returns 1 if end of file has been read, otherwise it
           returns an empty string.  Because the input is buffered this isn't
           the same thing as $obj has closed.  In other words $obj can be
           closed but there still can be stuff in the buffer to be read.
           Under this condition you can still read but you won't be able to
           write.

       errmode - define action to be performed on error
               $mode = $obj->errmode;

               $prev = $obj->errmode($mode);

           This method gets or sets the action used when errors are encoun-
           tered using the object.  The first calling sequence returns the
           current error mode.  The second calling sequence sets it to $mode
           and returns the previous mode.  Valid values for $mode are "die"
           (the default), "return", a coderef, or an arrayref.

           When mode is "die" and an error is encountered using the object,
           then an error message is printed to standard error and the program
           dies.

           When mode is "return" then the method generating the error places
           an error message in the object and returns an undefined value in a
           scalar context and an empty list in list context.  The error mes-
           sage may be obtained using "errmsg()".

           When mode is a coderef, then when an error is encountered coderef
           is called with the error message as its first argument.  Using this
           mode you may have your own subroutine handle errors.  If coderef
           itself returns then the method generating the error returns unde-
           fined or an empty list depending on context.

           When mode is an arrayref, the first element of the array must be a
           coderef.  Any elements that follow are the arguments to coderef.
           When an error is encountered, the coderef is called with its argu-
           ments.  Using this mode you may have your own subroutine handle
           errors.  If the coderef itself returns then the method generating
           the error returns undefined or an empty list depending on context.

           A warning is printed to STDERR when attempting to set this
           attribute to something that's not "die", "return", a coderef, or an
           arrayref whose first element isn't a coderef.

       errmsg - most recent error message
               $msg = $obj->errmsg;

               $prev = $obj->errmsg(@msgs);

           The first calling sequence returns the error message associated
           with the object.  The empty string is returned if no error has been
           encountered yet.  The second calling sequence sets the error mes-
           sage for the object to the concatenation of @msgs and returns the
           previous error message.  Normally, error messages are set inter-
           nally by a method when an error is encountered.

       error - perform the error mode action
               $obj->error(@msgs);

           This method concatenates @msgs into a string and places it in the
           object as the error message.  Also see "errmsg()".  It then per-
           forms the error mode action.  Also see "errmode()".

           If the error mode doesn't cause the program to die, then an
           undefined value or an empty list is returned depending on the con-
           text.

           This method is primarily used by this class or a sub-class to per-
           form the user requested action when an error is encountered.

       fhopen - use already open filehandle for I/O
               $ok = $obj->fhopen($fh);

           This method associates the open filehandle $fh with $obj for fur-
           ther I/O.  Filehandle $fh must already be opened.

           Suppose you want to use the features of this module to do I/O to
           something other than a TCP port, for example STDIN or a filehandle
           opened to read from a process.  Instead of opening the object for
           I/O to a TCP port by using "open()" or "new()", call this method
           instead.

           The value 1 is returned success, the error mode action is performed
           on failure.

       get - read block of data
               $data = $obj->get([Binmode    => $mode,]
                                 [Errmode    => $errmode,]
                                 [Telnetmode => $mode,]
                                 [Timeout    => $secs,]);

           This method reads a block of data from the object and returns it
           along with any buffered data.  If no buffered data is available to
           return, it will wait for data to read using the timeout specified
           in the object.  You can override that timeout using $secs.  Also
           see "timeout()".  If buffered data is available to return, it also
           checks for a block of data that can be immediately read.

           On eof an undefined value is returned.  On time-out or other fail-
           ures, the error mode action is performed.  To distinguish between
           eof or an error occurring when the error mode is not set to "die",
           use "eof()".

           Optional named parameters are provided to override the current set-
           tings of binmode, errmode, telnetmode, and timeout.

       getline - read next line
               $line = $obj->getline([Binmode    => $mode,]
                                     [Errmode    => $errmode,]
                                     [Input_record_separator => $chars,]
                                     [Rs         => $chars,]
                                     [Telnetmode => $mode,]
                                     [Timeout    => $secs,]);

           This method reads and returns the next line of data from the
           object.  You can use "input_record_separator()" to change the
           notion of what separates a line.  The default is "\n".  If a line
           isn't immediately available, this method blocks waiting for a line
           or a time-out.

           On eof an undefined value is returned.  On time-out or other fail-
           ures, the error mode action is performed.  To distinguish between
           eof or an error occurring when the error mode is not set to "die",
           use "eof()".

           Optional named parameters are provided to override the current set-
           tings of binmode, errmode, input_record_separator, rs, telnetmode,
           and timeout.  Rs is synonymous with input_record_separator.

       getlines - read next lines
               @lines = $obj->getlines([Binmode    => $mode,]
                                       [Errmode    => $errmode,]
                                       [Input_record_separator => $chars,]
                                       [Rs         => $chars,]
                                       [Telnetmode => $mode,]
                                       [Timeout    => $secs,]
                                       [All        => $boolean,]);

           This method reads and returns all the lines of data from the object
           until end of file is read.  You can use "input_record_separator()"
           to change the notion of what separates a line.  The default is
           "\n".  A time-out error occurs if all the lines can't be read
           within the time-out interval.  See "timeout()".

           The behavior of this method was changed in version 3.03.  Prior to
           version 3.03 this method returned just the lines available from the
           next read.  To get that old behavior, use the optional named param-
           eter All and set $boolean to "" or 0.

           If only eof is read then an empty list is returned.  On time-out or
           other failures, the error mode action is performed.  Use "eof()" to
           distinguish between reading only eof or an error occurring when the
           error mode is not set to "die".

           Optional named parameters are provided to override the current set-
           tings of binmode, errmode, input_record_separator, rs, telnetmode,
           and timeout.  Rs is synonymous with input_record_separator.

       host - name of remote host
               $host = $obj->host;

               $prev = $obj->host($host);

           This method designates the remote host for "open()".  With no argu-
           ment it returns the current host name set in the object.  With an
           argument it sets the current host name to $host and returns the
           previous host name.  You may indicate the remote host using either
           a hostname or an IP address.

           The default value is "localhost".  It may also be set by "open()"
           or "new()".

       input_log - log all input
               $fh = $obj->input_log;

               $fh = $obj->input_log($fh);

               $fh = $obj->input_log($filename);

           This method starts or stops logging of input.  This is useful when
           debugging.  Also see "dump_log()".  Because most command inter-
           preters echo back commands received, it's likely all your output
           will also be in this log.  Note that input logging occurs after
           newline translation.  See "binmode()" for details on newline trans-
           lation.

           If no argument is given, the log filehandle is returned.  An empty
           string indicates logging is off.

           To stop logging, use an empty string as an argument.

           If an open filehandle is given, it is used for logging and
           returned.  Otherwise, the argument is assumed to be the name of a
           file, the file is opened for logging and a filehandle to it is
           returned.  If the file can't be opened for writing, the error mode
           action is performed.

       input_record_separator - input line delimiter
               $chars = $obj->input_record_separator;

               $prev = $obj->input_record_separator($chars);

           This method designates the line delimiter for input.  It's used
           with "getline()", "getlines()", and "cmd()" to determine lines in
           the input.

           With no argument this method returns the current input record sepa-
           rator set in the object.  With an argument it sets the input record
           separator to $chars and returns the previous value.  Note that
           $chars must have length.

           A warning is printed to STDERR when attempting to set this
           attribute to a string with no length.

       last_prompt - last prompt read
               $string = $obj->last_prompt;

               $prev = $obj->last_prompt($string);

           With no argument this method returns the last prompt read by cmd()
           or login().  See "prompt()".  With an argument it sets the last
           prompt read to $string and returns the previous value.  Normally,
           only internal methods set the last prompt.

       lastline - last line read
               $line = $obj->lastline;

               $prev = $obj->lastline($line);

           This method retrieves the last line read from the object.  This may
           be a useful error message when the remote side abnormally closes
           the connection.  Typically the remote side will print an error mes-
           sage before closing.

           With no argument this method returns the last line read from the
           object.  With an argument it sets the last line read to $line and
           returns the previous value.  Normally, only internal methods set
           the last line.

       login - perform standard login
               $ok = $obj->login($username, $password);

               $ok = $obj->login(Name     => $username,
                                 Password => $password,
                                 [Errmode => $mode,]
                                 [Prompt  => $match,]
                                 [Timeout => $secs,]);

           This method performs a standard login by waiting for a login prompt
           and responding with $username, then waiting for the password prompt
           and responding with $password, and then waiting for the command
           interpreter prompt.  If any of those prompts sent by the remote
           side don't match what's expected, this method will time-out, unless
           timeout is turned off.

           Login prompt must match either of these case insensitive patterns:

               /login[: ]*$/i
               /username[: ]*$/i

           Password prompt must match this case insensitive pattern:

               /password[: ]*$/i

           The command interpreter prompt must match the current setting of
           prompt.  See "prompt()".

           Use "dump_log()" to debug when this method keeps timing-out and you
           don't think it should.

           Consider using a combination of "print()" and "waitfor()" as an
           alternative to this method when it doesn't do what you want, e.g.
           the remote host doesn't prompt for a username.

           On success, 1 is returned.  On time out, eof, or other failures,
           the error mode action is performed.  See "errmode()".

           Optional named parameters are provided to override the current set-
           tings of errmode, prompt, and timeout.

       max_buffer_length - maximum size of input buffer
               $len = $obj->max_buffer_length;

               $prev = $obj->max_buffer_length($len);

           This method designates the maximum size of the input buffer.  An
           error is generated when a read causes the buffer to exceed this
           limit.  The default value is 1,048,576 bytes (1MB).  The input
           buffer can grow much larger than the block size when you continu-
           ously read using "getline()" or "waitfor()" and the data stream
           contains no newlines or matching waitfor patterns.

           With no argument, this method returns the current maximum buffer
           length set in the object.  With an argument it sets the maximum
           buffer length to $len and returns the previous value.  Values of
           $len smaller than 512 will be adjusted to 512.

           A warning is printed to STDERR when attempting to set this
           attribute to something that isn't a positive integer.

       ofs - field separator for print
               $chars = $obj->ofs

               $prev = $obj->ofs($chars);

           This method is synonymous with "output_field_separator()".

       open - connect to port on remote host
               $ok = $obj->open($host);

               $ok = $obj->open([Host    => $host,]
                                [Port    => $port,]
                                [Errmode => $mode,]
                                [Timeout => $secs,]);

           This method opens a TCP connection to $port on $host.  If either
           argument is missing then the current value of "host()" or "port()"
           is used.  Optional named parameters are provided to override the
           current setting of errmode and timeout.

           On success 1 is returned.  On time-out or other connection fail-
           ures, the error mode action is performed.  See "errmode()".

           Time-outs don't work for this method on machines that don't imple-
           ment SIGALRM - most notably MS-Windows machines.  For those
           machines, an error is returned when the system reaches its own
           time-out while trying to connect.

           A side effect of this method is to reset the alarm interval associ-
           ated with SIGALRM.

       option_accept - indicate willingness to accept a TELNET option
               $fh = $obj->option_accept([Do   => $telopt,]
                                         [Dont => $telopt,]
                                         [Will => $telopt,]
                                         [Wont => $telopt,]);

           This method is used to indicate whether to accept or reject an
           offer to enable a TELNET option made by the remote side.  If you're
           using Do or Will to indicate a willingness to enable, then a noti-
           fication callback must have already been defined by a prior call to
           "option_callback()".  See "option_callback()" for details on
           receiving enable/disable notification of a TELNET option.

           You can give multiple Do, Dont, Will, or Wont arguments for differ-
           ent TELNET options in the same call to this method.

           The following example describes the meaning of the named parame-
           ters.  A TELNET option, such as "TELOPT_ECHO" used below, is an
           integer constant that you can import from Net::Telnet.  See the
           source in file Telnet.pm for the complete list.

           *   Do => "TELOPT_ECHO"

               *   we'll accept an offer to enable the echo option on the
                   local side

           *   Dont => "TELOPT_ECHO"

               *   we'll reject an offer to enable the echo option on the
                   local side

           *   Will => "TELOPT_ECHO"

               *   we'll accept an offer to enable the echo option on the
                   remote side

           *   Wont => "TELOPT_ECHO"

               *   we'll reject an offer to enable the echo option on the
                   remote side

       *   Use "option_send()" to send a request to the remote side to enable
           or disable a particular TELNET option.

       option_callback - define the option negotiation callback
               $coderef = $obj->option_callback;

               $prev = $obj->option_callback($coderef);

           This method defines the callback subroutine that's called when a
           TELNET option is enabled or disabled.  Once defined, the
           option_callback may not be undefined.  However, calling this method
           with a different $coderef changes it.

           A warning is printed to STDERR when attempting to set this
           attribute to something that isn't a coderef.

           Here are the circumstances that invoke $coderef:

           *   An option becomes enabled because the remote side requested an
               enable and "option_accept()" had been used to arrange that it
               be accepted.

           *   The remote side arbitrarily decides to disable an option that
               is currently enabled.  Note that Net::Telnet always accepts a
               request to disable from the remote side.

           *   "option_send()" was used to send a request to enable or disable
               an option and the response from the remote side has just been
               received.  Note, that if a request to enable is rejected then
               $coderef is still invoked even though the option didn't change.

       *   Here are the arguments passed to &$coderef:

               &$coderef($obj, $option, $is_remote,
                         $is_enabled, $was_enabled, $buf_position);

           *   1.  $obj is the Net::Telnet object

           *   2.  $option is the TELNET option.  Net::Telnet exports con-
               stants for the various TELNET options which just equate to an
               integer.

           *   3.  $is_remote is a boolean indicating for which side the
               option applies.

           *   4.  $is_enabled is a boolean indicating the option is enabled
               or disabled

           *   5.  $was_enabled is a boolean indicating the option was previ-
               ously enabled or disabled

           *   6.  $buf_position is an integer indicating the position in the
               object's input buffer where the option takes effect.  See
               "buffer()" to access the object's input buffer.

       option_log - log all TELNET options sent or received
               $fh = $obj->option_log;

               $fh = $obj->option_log($fh);

               $fh = $obj->option_log($filename);

           This method starts or stops logging of all TELNET options being
           sent or received.  This is useful for debugging when you send
           options via "option_send()" or you arrange to accept option
           requests from the remote side via "option_accept()".  Also see
           "dump_log()".

           If no argument is given, the log filehandle is returned.  An empty
           string indicates logging is off.

           To stop logging, use an empty string as an argument.

           If an open filehandle is given, it is used for logging and
           returned.  Otherwise, the argument is assumed to be the name of a
           file, the file is opened for logging and a filehandle to it is
           returned.  If the file can't be opened for writing, the error mode
           action is performed.

       option_send - send TELNET option negotiation request
               $ok = $obj->option_send([Do    => $telopt,]
                                       [Dont  => $telopt,]
                                       [Will  => $telopt,]
                                       [Wont  => $telopt,]
                                       [Async => $boolean,]);

           This method is not yet implemented.  Look for it in a future ver-
           sion.

       option_state - get current state of a TELNET option
               $hashref = $obj->option_state($telopt);

           This method returns a hashref containing a copy of the current
           state of TELNET option $telopt.

           Here are the values returned in the hash:

           *   $hashref->{remote_enabled}

               *   boolean that indicates if the option is enabled on the
                   remote side.

           *   $hashref->{remote_enable_ok}

               *   boolean that indicates if it's ok to accept an offer to
                   enable this option on the remote side.

           *   $hashref->{remote_state}

               *   string used to hold the internal state of option negotia-
                   tion for this option on the remote side.

           *   $hashref->{local_enabled}

               *   boolean that indicates if the option is enabled on the
                   local side.

           *   $hashref->{local_enable_ok}

               *   boolean that indicates if it's ok to accept an offer to
                   enable this option on the local side.

           *   $hashref->{local_state}

               *   string used to hold the internal state of option negotia-
                   tion for this option on the local side.

       ors - output line delimiter
               $chars = $obj->ors;

               $prev = $obj->ors($chars);

           This method is synonymous with "output_record_separator()".

       output_field_separator - field separator for print
               $chars = $obj->output_field_separator;

               $prev = $obj->output_field_separator($chars);

           This method designates the output field separator for "print()".
           Ordinarily the print method simply prints out the comma separated
           fields you specify.  Set this to specify what's printed between
           fields.

           With no argument this method returns the current output field sepa-
           rator set in the object.  With an argument it sets the output field
           separator to $chars and returns the previous value.

           By default it's set to an empty string.

       output_log - log all output
               $fh = $obj->output_log;

               $fh = $obj->output_log($fh);

               $fh = $obj->output_log($filename);

           This method starts or stops logging of output.  This is useful when
           debugging.  Also see "dump_log()".  Because most command inter-
           preters echo back commands received, it's likely all your output
           would also be in an input log.  See "input_log()".  Note that out-
           put logging occurs before newline translation.  See "binmode()" for
           details on newline translation.

           If no argument is given, the log filehandle is returned.  An empty
           string indicates logging is off.

           To stop logging, use an empty string as an argument.

           If an open filehandle is given, it is used for logging and
           returned.  Otherwise, the argument is assumed to be the name of a
           file, the file is opened for logging and a filehandle to it is
           returned.  If the file can't be opened for writing, the error mode
           action is performed.

       output_record_separator - output line delimiter
               $chars = $obj->output_record_separator;

               $prev = $obj->output_record_separator($chars);

           This method designates the output line delimiter for "print()" and
           "cmd()".  Set this to specify what's printed at the end of
           "print()" and "cmd()".

           The output record separator is set to "\n" by default, so there's
           no need to append all your commands with a newline.  To avoid
           printing the output_record_separator use "put()" or set the out-
           put_record_separator to an empty string.

           With no argument this method returns the current output record sep-
           arator set in the object.  With an argument it sets the output
           record separator to $chars and returns the previous value.

       port - remote port
               $port = $obj->port;

               $prev = $obj->port($port);

           This method designates the remote TCP port.  With no argument this
           method returns the current port number.  With an argument it sets
           the current port number to $port and returns the previous port.  If
           $port is a TCP service name, then it's first converted to a port
           number using the perl function "getservbyname()".

           The default value is 23.  It may also be set by "open()" or
           "new()".

           A warning is printed to STDERR when attempting to set this
           attribute to something that's not a positive integer or a valid TCP
           service name.

       print - write to object
               $ok = $obj->print(@list);

           This method writes @list followed by the output_record_separator to
           the open object and returns 1 if all data was successfully written.
           On time-out or other failures, the error mode action is performed.
           See "errmode()".

           By default, the "output_record_separator()" is set to "\n" so all
           your commands automatically end with a newline.  In most cases your
           output is being read by a command interpreter which won't accept a
           command until newline is read.  This is similar to someone typing a
           command and hitting the return key.  To avoid printing a trailing
           "\n" use "put()" instead or set the output_record_separator to an
           empty string.

           On failure, it's possible that some data was written.  If you
           choose to try and recover from a print timing-out, use
           "print_length()" to determine how much was written before the error
           occurred.

           You may also use the output field separator to print a string
           between the list elements.  See "output_field_separator()".

       print_length - number of bytes written by print
               $num = $obj->print_length;

           This returns the number of bytes successfully written by the most
           recent "print()" or "put()".

       prompt - pattern to match a prompt
               $matchop = $obj->prompt;

               $prev = $obj->prompt($matchop);

           This method sets the pattern used to find a prompt in the input
           stream.  It must be a string representing a valid perl pattern
           match operator.  The methods "login()" and "cmd()" try to read
           until matching the prompt.  They will fail with a time-out error if
           the pattern you've chosen doesn't match what the remote side sends.

           With no argument this method returns the prompt set in the object.
           With an argument it sets the prompt to $matchop and returns the
           previous value.

           The default prompt is '/[\$%#>] $/'

           Always use single quotes, instead of double quotes, to construct
           $matchop (e.g. '/bash\$ $/').  If you're constructing a DOS like
           file path, you'll need to use four backslashes to represent one
           (e.g. '/c:\\\\users\\\\bill>$/i').

           Of course don't forget about regexp metacharacters like ".", "[",
           or "$".  You'll only need a single backslash to quote them.  The
           anchor metacharacters "^" and "$" refer to positions in the input
           buffer.

           A warning is printed to STDERR when attempting to set this
           attribute with a match operator missing its opening delimiter.

       put - write to object
               $ok = $obj->put($string);

               $ok = $obj->put(String      => $string,
                               [Binmode    => $mode,]
                               [Errmode    => $errmode,]
                               [Telnetmode => $mode,]
                               [Timeout    => $secs,]);

           This method writes $string to the opened object and returns 1 if
           all data was successfully written.  This method is like "print()"
           except that it doesn't write the trailing output_record_separator
           ("\n" by default).  On time-out or other failures, the error mode
           action is performed.  See "errmode()".

           On failure, it's possible that some data was written.  If you
           choose to try and recover from a put timing-out, use
           "print_length()" to determine how much was written before the error
           occurred.

           Optional named parameters are provided to override the current set-
           tings of binmode, errmode, telnetmode, and timeout.

       rs - input line delimiter
               $chars = $obj->rs;

               $prev = $obj->rs($chars);

           This method is synonymous with "input_record_separator()".

       telnetmode - turn off/on telnet command interpretation
               $mode = $obj->telnetmode;

               $prev = $obj->telnetmode($mode);

           This method controls whether or not TELNET commands in the data
           stream are recognized and handled.  The TELNET protocol uses cer-
           tain character sequences sent in the data stream to control the
           session.  If the port you're connecting to isn't using the TELNET
           protocol, then you should turn this mode off.  The default is on.

           If no argument is given, the current mode is returned.

           If $mode is 0 then telnet mode is off.  If $mode is 1 then telnet
           mode is on.

       timed_out - time-out indicator
               $boolean = $obj->timed_out;

               $prev = $obj->timed_out($boolean);

           This method indicates if a previous read, write, or open method
           timed-out.  Remember that timing-out is itself an error.  To be
           able to invoke "timed_out()" after a time-out error, you'd have to
           change the default error mode to something other than "die".  See
           "errmode()".

           With no argument this method returns 1 if the previous method
           timed-out.  With an argument it sets the indicator.  Normally, only
           internal methods set this indicator.

       timeout - I/O time-out interval
               $secs = $obj->timeout;

               $prev = $obj->timeout($secs);

           This method sets the timeout interval that's used when performing
           I/O or connecting to a port.  When a method doesn't complete within
           the timeout interval then it's an error and the error mode action
           is performed.

           A timeout may be expressed as a relative or absolute value.  If
           $secs is greater than or equal to the time the program started, as
           determined by $^T, then it's an absolute time value for when time-
           out occurs.  The perl function "time()" may be used to obtain an
           absolute time value.  For a relative time-out value less than $^T,
           time-out happens $secs from when the method begins.

           If $secs is 0 then time-out occurs if the data cannot be immedi-
           ately read or written.  Use the undefined value to turn off timing-
           out completely.

           With no argument this method returns the timeout set in the object.
           With an argument it sets the timeout to $secs and returns the pre-
           vious value.  The default timeout value is 10 seconds.

           A warning is printed to STDERR when attempting to set this
           attribute to something that's not an "undef" or a non-negative
           integer.

       waitfor - wait for pattern in the input
               $ok = $obj->waitfor($matchop);
               $ok = $obj->waitfor([Match      => $matchop,]
                                   [String     => $string,]
                                   [Binmode    => $mode,]
                                   [Errmode    => $errmode,]
                                   [Telnetmode => $mode,]
                                   [Timeout    => $secs,]);

               ($prematch, $match) = $obj->waitfor($matchop);
               ($prematch, $match) = $obj->waitfor([Match      => $matchop,]
                                                   [String     => $string,]
                                                   [Binmode    => $mode,]
                                                   [Errmode    => $errmode,]
                                                   [Telnetmode => $mode,]
                                                   [Timeout    => $secs,]);

           This method reads until a pattern match or string is found in the
           input stream.  All the characters before and including the match
           are removed from the input stream.

           In a list context the characters before the match and the matched
           characters are returned in $prematch and $match.  In a scalar con-
           text, the matched characters and all characters before it are dis-
           carded and 1 is returned on success.  On time-out, eof, or other
           failures, for both list and scalar context, the error mode action
           is performed.  See "errmode()".

           You can specify more than one pattern or string by simply providing
           multiple Match and/or String named parameters.  A $matchop must be
           a string representing a valid Perl pattern match operator.  The
           $string is just a substring to find in the input stream.

           Use "dump_log()" to debug when this method keeps timing-out and you
           don't think it should.

           An optional named parameter is provided to override the current
           setting of timeout.

           To avoid unexpected backslash interpretation, always use single
           quotes instead of double quotes to construct a match operator argu-
           ment for "prompt()" and "waitfor()" (e.g. '/bash\$ $/').  If you're
           constructing a DOS like file path, you'll need to use four back-
           slashes to represent one (e.g. '/c:\\\\users\\\\bill>$/i').

           Of course don't forget about regexp metacharacters like ".", "[",
           or "$".  You'll only need a single backslash to quote them.  The
           anchor metacharacters "^" and "$" refer to positions in the input
           buffer.

           Optional named parameters are provided to override the current set-
           tings of binmode, errmode, telnetmode, and timeout.

SEE ALSO
       RFC 854
         TELNET Protocol Specification

         ftp://ftp.isi.edu/in-notes/rfc854.txt

       RFC 1143
         Q Method of Implementing TELNET Option Negotiation

         ftp://ftp.isi.edu/in-notes/rfc1143.txt

       TELNET Option Assignments
         http://www.iana.org/assignments/telnet-options

EXAMPLES
       This example gets the current weather forecast for Brainerd, Minnesota.

           my ($forecast, $t);

           use Net::Telnet ();
           $t = new Net::Telnet;
           $t->open("rainmaker.wunderground.com");

           ## Wait for first prompt and "hit return".
           $t->waitfor('/continue:.*$/');
           $t->print("");

           ## Wait for second prompt and respond with city code.
           $t->waitfor('/city code.*$/');
           $t->print("BRD");

           ## Read and print the first page of forecast.
           ($forecast) = $t->waitfor('/[ \t]+press return to continue/i');
           print $forecast;

           exit;

       This example checks a POP server to see if you have mail.

           my ($hostname, $line, $passwd, $pop, $username);

           $hostname = "your_destination_host_here";
           $username = "your_username_here";
           $passwd = "your_password_here";

           use Net::Telnet ();
           $pop = new Net::Telnet (Telnetmode => 0);
           $pop->open(Host => $hostname,
                      Port => 110);

           ## Read connection message.
           $line = $pop->getline;
           die $line unless $line =~ /^\+OK/;

           ## Send user name.
           $pop->print("user $username");
           $line = $pop->getline;
           die $line unless $line =~ /^\+OK/;

           ## Send password.
           $pop->print("pass $passwd");
           $line = $pop->getline;
           die $line unless $line =~ /^\+OK/;

           ## Request status of messages.
           $pop->print("list");
           $line = $pop->getline;
           print $line;

           exit;

       Here's an example that uses the ssh program to connect to a remote
       host.  Because the ssh program reads and writes to its controlling ter-
       minal, the IO::Pty module is used to create a new pseudo terminal for
       use by ssh.  A new Net::Telnet object is then created to read and write
       to that pseudo terminal.  To use the code below, substitute "changeme"
       with the actual host, user, password, and command prompt.

           ## Main program.
           {
               my ($pty, $ssh, @lines);
               my $host = "changeme";
               my $user = "changeme";
               my $password = "changeme";
               my $prompt = '/changeme:~> $/';

               ## Start ssh program.
               $pty = &spawn("ssh", "-l", $user, $host);  # spawn() defined below

               ## Create a Net::Telnet object to perform I/O on ssh's tty.
               use Net::Telnet;
               $ssh = new Net::Telnet (-fhopen => $pty,
                                       -prompt => $prompt,
                                       -telnetmode => 0,
                                       -cmd_remove_mode => 1,
                                       -output_record_separator => "\r");

               ## Login to remote host.
               $ssh->waitfor(-match => '/password: ?$/i',
                             -errmode => "return")
                   or die "problem connecting to host: ", $ssh->lastline;
               $ssh->print($password);
               $ssh->waitfor(-match => $ssh->prompt,
                             -errmode => "return")
                   or die "login failed: ", $ssh->lastline;

               ## Send command, get and print its output.
               @lines = $ssh->cmd("who");
               print @lines;

               exit;
           } # end main program

           sub spawn {
               my(@cmd) = @_;
               my($pid, $pty, $tty, $tty_fd);

               ## Create a new pseudo terminal.
               use IO::Pty ();
               $pty = new IO::Pty
                   or die $!;

               ## Execute the program in another process.
               unless ($pid = fork) {  # child process
                   die "problem spawning program: $!\n" unless defined $pid;

                   ## Disassociate process from existing controlling terminal.
                   use POSIX ();
                   POSIX::setsid
                       or die "setsid failed: $!";

                   ## Associate process with a new controlling terminal.
                   $tty = $pty->slave;
                   $tty_fd = $tty->fileno;
                   close $pty;

                   ## Make stdio use the new controlling terminal.
                   open STDIN, "<&$tty_fd" or die $!;
                   open STDOUT, ">&$tty_fd" or die $!;
                   open STDERR, ">&STDOUT" or die $!;
                   close $tty;

                   ## Execute requested program.
                   exec @cmd
                       or die "problem executing $cmd[0]\n";
               } # end child process

               $pty;
           } # end sub spawn

       Here's an example that changes a user's login password.  Because the
       passwd program always prompts for passwords on its controlling termi-
       nal, the IO::Pty module is used to create a new pseudo terminal for use
       by passwd.  A new Net::Telnet object is then created to read and write
       to that pseudo terminal.  To use the code below, substitute "changeme"
       with the actual old and new passwords.

           my ($pty, $passwd);
           my $oldpw = "changeme";
           my $newpw = "changeme";

           ## Start passwd program.
           $pty = &spawn("passwd");  # spawn() defined above

           ## Create a Net::Telnet object to perform I/O on passwd's tty.
           use Net::Telnet;
           $passwd = new Net::Telnet (-fhopen => $pty,
                                      -timeout => 2,
                                      -output_record_separator => "\r",
                                      -telnetmode => 0,
                                      -cmd_remove_mode => 1);
           $passwd->errmode("return");

           ## Send existing password.
           $passwd->waitfor('/password: ?$/i')
               or die "no old password prompt: ", $passwd->lastline;
           $passwd->print($oldpw);

           ## Send new password.
           $passwd->waitfor('/new password: ?$/i')
               or die "bad old password: ", $passwd->lastline;
           $passwd->print($newpw);

           ## Send new password verification.
           $passwd->waitfor('/new password: ?$/i')
               or die "bad new password: ", $passwd->lastline;
           $passwd->print($newpw);

           ## Display success or failure.
           $passwd->waitfor('/changed/')
               or die "bad new password: ", $passwd->lastline;
           print $passwd->lastline;

           $passwd->close;
           exit;

       Here's an example you can use to down load a file of any type.  The
       file is read from the remote host's standard output using cat.  To pre-
       vent any output processing, the remote host's standard output is put in
       raw mode using the Bourne shell.  The Bourne shell is used because some
       shells, notably tcsh, prevent changing tty modes.  Upon completion, FTP
       style statistics are printed to stderr.

           my ($block, $filename, $host, $hostname, $k_per_sec, $line,
               $num_read, $passwd, $prevblock, $prompt, $size, $size_bsd,
               $size_sysv, $start_time, $total_time, $username);

           $hostname = "your_destination_host_here";
           $username = "your_username_here";
           $passwd = "your_password_here";
           $filename = "your_download_file_here";

           ## Connect and login.
           use Net::Telnet ();
           $host = new Net::Telnet (Timeout => 30,
                                    Prompt => '/[%#>] $/');
           $host->open($hostname);
           $host->login($username, $passwd);

           ## Make sure prompt won't match anything in send data.
           $prompt = "_funkyPrompt_";
           $host->prompt("/$prompt\$/");
           $host->cmd("set prompt = '$prompt'");

           ## Get size of file.
           ($line) = $host->cmd("/bin/ls -l $filename");
           ($size_bsd, $size_sysv) = (split ' ', $line)[3,4];
           if ($size_sysv =~ /^\d+$/) {
               $size = $size_sysv;
           }
           elsif ($size_bsd =~ /^\d+$/) {
               $size = $size_bsd;
           }
           else {
               die "$filename: no such file on $hostname";
           }

           ## Start sending the file.
           binmode STDOUT;
           $host->binmode(1);
           $host->print("/bin/sh -c 'stty raw; cat $filename'");
           $host->getline;    # discard echoed back line

           ## Read file a block at a time.
           $num_read = 0;
           $prevblock = "";
           $start_time = time;
           while (($block = $host->get) and ($block !~ /$prompt$/o)) {
               if (length $block >= length $prompt) {
                   print $prevblock;
                   $num_read += length $prevblock;
                   $prevblock = $block;
               }
               else {
                   $prevblock .= $block;
               }

           }
           $host->close;

           ## Print last block without trailing prompt.
           $prevblock .= $block;
           $prevblock =~ s/$prompt$//;
           print $prevblock;
           $num_read += length $prevblock;
           die "error: expected size $size, received size $num_read\n"
               unless $num_read == $size;

           ## Print totals.
           $total_time = (time - $start_time) || 1;
           $k_per_sec = ($size / 1024) / $total_time;
           $k_per_sec = sprintf "%3.1f", $k_per_sec;
           warn("$num_read bytes received in $total_time seconds ",
                "($k_per_sec Kbytes/s)\n");

           exit;

AUTHOR
       Jay Rogers <jay@rgrs.com>

COPYRIGHT
       Copyright 1997, 2000, 2002 by Jay Rogers.  All rights reserved.  This
       program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.8.8                       2007-12-23                  Net::Telnet(3pm)

Time taken: 0.00052 seconds


Created with the man page lookup class by Andrew Collington, php@amnuts.com