SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from Fedora 28 perl-Net-Telnet-3.04-7.fc28.noarch.rpm

Net::Telnet

Section: User Contributed Perl Documentation (3)
Updated: 2013-04-21
Index 

NAME

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

SYNOPSIS

"use Net::Telnet ();"

see METHODS or EXAMPLES sections below 

DESCRIPTION

Net::Telnet allows you to make client connections to a TCP port and donetwork I/O, especially to a port using the TELNET protocol. SimpleI/O methods such as print, get, and getline are provided. Moresophisticated interactive features are provided because connecting toa TELNET port ultimately means communicating with a program designedfor human interaction. These interactive features include the abilityto specify a time-out and to wait for patterns to appear in the inputstream, such as the prompt from a shell. IPv6 support is availablewhen using perl 5.14 or later (see "family()".

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

*
You're not familiar with sockets and you want a simple way to makeclient connections to TCP services.
*
You want to be able to specify your own time-out while connecting,reading, or writing.
*
You're communicating with an interactive program at the other end ofsome socket or pipe and you want to wait for certain patterns toappear.

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

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

See the EXAMPLES section below for more examples.

Usage questions should be directed to the perlmonks.org discussiongroup. Bugs can be viewed or reported at cpan.org on the Net::Telnetpage. 

What To Know Before Using

*
All output is flushed while all input is buffered. Each objectcontains its own input buffer.
*
The output record separator for "print()" and "cmd()" is set to"\n" by default, so that you don't have to append all your commandswith a newline. To avoid printing a trailing "\n" use "put()" orset the output_record_separator to "".
*
The methods "login()" and "cmd()" use the prompt setting in theobject to determine when a login or remote command is complete. Thosemethods will fail with a time-out if you don't set the promptcorrectly.
*
Use a combination of "print()" and "waitfor()" as an alternative to"login()" or "cmd()" when they don't do what you want.
*
Errors such as timing-out are handled according to the error modeaction. The default action is to print an error message to standarderror and have the program die. See the "errmode()" method for moreinformation.
*
When constructing the match operator argument for "prompt()" or"waitfor()", always use single quotes instead of double quotes toavoid unexpected backslash interpretation (e.g. '/bash\$ $/'). Ifyou're constructing a DOS like file path, you'll need to use fourbackslashes 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 anchormetacharacters "^" and "$" refer to positions in the input buffer.To avoid matching characters read that look like a prompt, it's a goodidea to end your prompt pattern with the "$" anchor. That way theprompt will only match if it's the last thing read.

*
In the input stream, each sequence of carriage return and linefeed (i.e. "\015\012" or CR LF) is converted to "\n". In theoutput stream, each occurrence of "\n" is converted to a sequenceof CR LF. See "binmode()" to change the behavior. TCP protocolstypically use the ASCII sequence, carriage return and line feed todesignate a newline.
*
Timing-out while making a connection is disabled for machines thatdon't support the "alarm()" function. Most notably these includeMS-Windows machines.
*
You'll need to be running at least Perl version 5.002 to use thismodule. This module does not require any libraries that don't alreadycome with a standard Perl distribution.

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

 

Debugging

The typical usage bug causes a time-out error because you've madeincorrect assumptions about what the remote side actually sends. Theeasiest way to reconcile what the remote side sends with yourexpectations is to use "input_log()" or "dump_log()".

"dump_log()" allows you to see the data being sent from the remoteside before any translation is done, while "input_log()" shows youthe results after translation. The translation includes convertingend of line characters, removing and responding to TELNET protocolcommands in the data stream. 

Style of Named Parameters

Two different styles of named parameters are supported. This documentonly 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. Howeverthird party TELNET servers are available. Unfortunately many of theseservers falsely claim to be a TELNET server. This is especially trueof the so-called ``Microsoft Telnet Server'' that comes installed withsome newer versions MS-Windows.

When a TELNET server first accepts a connection, it must use the ASCIIcontrol characters carriage-return and line-feed to start a new line(see RFC854). A server like the ``Microsoft Telnet Server'' thatdoesn't do this, isn't a TELNET server. These servers send ANSIterminal escape sequences to position to a column on a subsequent lineand to even position while writing characters that are adjacent toeach other. Worse, when sending output these servers resendpreviously sent command output in a misguided attempt to display anentire terminal screen.

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

METHODS

In the calling sequences below, square brackets [] representoptional 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,]                            [Family     => $family,]                            [Fhopen     => $filehandle,]                            [Host       => $host,]                            [Input_log  => $file,]                            [Input_record_separator => $chars,]                            [Localfamily => $family,]                            [Localhost   => $host,]                            [Max_buffer_length => $len,]                            [Ofs        => $chars,]                            [Option_log => $file,]                            [Ors        => $chars,]                            [Output_field_separator => $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 isreturned on success, the error mode action is performed on failure -see "errmode()". The optional arguments are short-cuts to methods ofthe same name.

If the $host argument is given then the object is opened byconnecting to TCP $port on $host. Also see "open()". The newobject returned is given the following defaults in the absence ofcorresponding named parameters:

*
The default Host is "localhost"
*
The default Port is 23
*
The default Family is "ipv4"
*
The default Prompt is '/[\$%#>] $/'
*
The default Timeout is 10
*
The default Errmode is "die"
*
The default Output_record_separator is "\n". Note that Orsis synonymous with Output_record_separator.
*
The default Input_record_separator is "\n". Note that Rs issynonymous with Input_record_separator.
*
The default Binmode is 0, which means do newline translation.
*
The default Telnetmode is 1, which means respond to TELNETcommands in the data stream.
*
The default Cmd_remove_mode is "auto"
*
The defaults for Dump_log, Input_log, Option_log, andOutput_log are "", which means that logging is turned-off.
*
The default Max_buffer_length is 1048576 bytes, i.e. 1 MiB.
*
The default Output_field_separator is "". Note that Ofsis synonymous with Output_field_separator.
*
The default Localhost is ""
*
The default Localfamily is "ipv4"
binmode - toggle newline translation
    $mode = $obj->binmode;    $prev = $obj->binmode($mode);

This method controls whether or not sequences of carriage returns andline feeds (CR LF or more specifically "\015\012") are translated.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 isnot done.

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

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

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

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

This method returns 1 on success, or performs the error mode actionon 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 theremote side but has yet to be read by the user. Modifications to theinput 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 theobject. 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 characterssent 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 ofcommand prompting interpreter such as a shell.

The command $string is automatically appended with theoutput_record_separator, by default it is "\n". This is similarto someone typing a command and hitting the return key. Set theoutput_record_separator to change this behavior.

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

In a list context, just the output generated by the command isreturned, one line per element. In other words, all the characters inbetween the echoed back command string and the prompt are returned.If the command happens to return no output, a list containing oneelement, the empty string is returned. This is so the list willindicate true in a boolean context. On time-out, eof, or otherfailures, 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 mostsituations, this method removes the first line returned from theremote 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 youdon't think it should.

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

The Output named parameter provides an alternative method ofreceiving command output. If you pass a scalar reference, all theoutput (even if it contains multiple lines) is returned in thereferenced scalar. If you pass an array or hash reference, the linesof output are returned in the referenced array or hash. You can use"input_record_separator()" to change the notion of what separates aline.

Optional named parameters are provided to override the currentsettings of cmd_remove_mode, errmode, input_record_separator, ors,output_record_separator, prompt, rs, and timeout. Rs is synonymouswith input_record_separator and ors is synonymous withoutput_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 theoutput returned by cmd(). Typically, when you send a command to theremote side, the first line of output returned is the command echoedback. Use this mode to remove the first line of output normallyreturned by cmd().

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

If $mode is 0 then the command output returned from cmd() has nolines 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 ornot the first line of command output is stripped, depends on whetheror not the remote side offered to echo. By default, Net::Telnetalways accepts an offer to echo by the remote side. You can changethe default to reject such an offer using "option_accept()".

A warning is printed to STDERR when attempting to set this attributeto something that is 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'sinput and output. The dump format shows the blocks read and writtenin a hexadecimal and printable character format. This method isuseful when debugging, however you might want to first try"input_log()" as it's more readable.

If no argument is given, the log filehandle is returned. A returnedempty string indicates logging is off.

To stop logging, use an empty string as an argument. The stoppedfilehandle is not closed.

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, thefilename is opened for logging and a filehandle to it is returned. Ifthe filehandle is not already opened or the filename can't be openedfor writing, the error mode action is performed.

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

This method returns 1 if end of file has been read, otherwise itreturns an empty string. Because the input is buffered this isn't thesame thing as $obj has closed. In other words $obj can beclosed but there still can be stuff in the buffer to be read. Underthis 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 encounteredusing the object. The first calling sequence returns the currenterror mode. The second calling sequence sets it to $mode andreturns 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 programdies.

When mode is "return" then the method generating the error placesan error message in the object and returns an undefined value in ascalar context and an empty list in list context. The error messagemay be obtained using "errmsg()".

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

When mode is an arrayref, the first element of the array must be acoderef. Any elements that follow are the arguments to coderef.When an error is encountered, the coderef is called with itsarguments. Using this mode you may have your own subroutine handleerrors. If the coderef itself returns then the method generatingthe error returns undefined or an empty list depending on context.

A warning is printed to STDERR when attempting to set this attributeto something that is not "die", "return", a coderef, or anarrayref 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 withthe object. The empty string is returned if no error has beenencountered yet. The second calling sequence sets the error messagefor the object to the concatenation of @msgs and returns theprevious error message. Normally, error messages are set internallyby 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 theobject as the error message. Also see "errmsg()". It then performsthe error mode action. Also see "errmode()".

If the error mode doesn't cause the program to die, then an undefinedvalue or an empty list is returned depending on the context.

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

family - IP address family for remote host
    $family = $obj->family;    $prev   = $obj->family($family);

This method designates which IP address family "host()" refers to,i.e. IPv4 or IPv6. IPv6 support is available when using perl 5.14 orlater. With no argument it returns the current value set in theobject. With an argument it sets the current address family to$family and returns the previous address family. Valid values are"ipv4", "ipv6", or "any". When "any", the "host()" canbe a hostname or IP address for either IPv4 or IPv6. Afterconnecting, you can use "sockfamily()" to determine which IP addressfamily was used.

The default value is "ipv4".

The error mode action is performed when attempting to set thisattribute to something that isn't "ipv4", "ipv6", or "any".It is also performed when attempting to set it to "ipv6" when theSocket module is less than version 1.94 or IPv6 is not supported inthe OS as indicated by Socket::AF_INET6 not being defined.

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

This method associates the open filehandle $fh with $obj forfurther I/O. Filehandle $fh must already be opened.

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

The value 1 is returned success, the error mode action is performedon 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 alongwith any buffered data. If no buffered data is available to return,it will wait for data to read using the timeout specified in theobject. You can override that timeout using $secs. Also see"timeout()". If buffered data is available to return, it also checksfor a block of data that can be immediately read.

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

Optional named parameters are provided to override the currentsettings 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 whatseparates a line. The default is "\n". If a line isn'timmediately available, this method blocks waiting for a line or atime-out.

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

Optional named parameters are provided to override the currentsettings 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 objectuntil end of file is read. You can use "input_record_separator()" tochange 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 thetime-out interval. See "timeout()".

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

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

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

host - name or IP address of remote host
    $host = $obj->host;    $prev = $obj->host($host);

This method designates the remote host for "open()". It is either ahostname or an IP address. With no argument it returns the currentvalue set in the object. With an argument it sets the current hostname to $host and returns the previous value. Use "family()" tocontrol which IP address family, IPv4 or IPv6, host refers to.

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 whendebugging. Also see "dump_log()". Because most command interpretersecho back commands received, it's likely all your output will also bein this log. Note that input logging occurs after newlinetranslation. See "binmode()" for details on newline translation.

If no argument is given, the log filehandle is returned. A returnedempty string indicates logging is off.

To stop logging, use an empty string as an argument. The stoppedfilehandle is not closed.

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, thefilename is opened for logging and a filehandle to it is returned. Ifthe filehandle is not already opened or the filename can't be openedfor 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 theinput.

With no argument this method returns the current input recordseparator set in the object. With an argument it sets the inputrecord separator to $chars and returns the previous value. Notethat $chars must have length.

A warning is printed to STDERR when attempting to set this attributeto 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() orlogin(). See "prompt()". With an argument it sets the last promptread to $string and returns the previous value. Normally, onlyinternal 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 bea useful error message when the remote side abnormally closes theconnection. Typically the remote side will print an error messagebefore closing.

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

localfamily - IP address family for local host
    $localfamily = $obj->localfamily;    $prev   = $obj->localfamily($family);

This method designates which IP address family "localhost()" refersto, i.e. IPv4 or IPv6. IPv6 support is available when using perl 5.14or later. With no argument it returns the current value set in theobject. With an argument it sets the current local address family to$family and returns the previous address family. Valid valuesare "ipv4", "ipv6", or "any". When "any", the"localhost()" can be a hostname or IP address for either IPv4 orIPv6.

The default value is "ipv4".

The error mode action is performed when attempting to set thisattribute to something that isn't "ipv4", "ipv6", or "any".It is also performed when attempting to set it to "ipv6" when theSocket module is less than version 1.94 or IPv6 is not supported inthe OS as indicated by Socket::AF_INET6 not being defined.

localhost - bind local socket to a specific network interface
    $localhost = $obj->localhost;    $prev = $obj->localhost($host);

This method designates the local socket IP address for "open()". Itis either a hostname, an IP address, or a null string (i.e. ""). Anull string disables this feature.

Normally the OS picks which local network interface to use. Thismethod is useful when the local machine has more than one networkinterface and you want to bind to a specific one. With no argument itreturns the current value set in the object. With an argument it setsthe current local host name to $host and returns the previousvalue. Use "localfamily()" to control which IP address family, IPv4or IPv6, local host refers to.

The default value is "".

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 promptand responding with $username, then waiting for the password promptand responding with $password, and then waiting for the commandinterpreter prompt. If any of those prompts sent by the remote sidedon't match what's expected, this method will time-out, unless timeoutis 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 ofprompt. See "prompt()".

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

Consider using a combination of "print()" and "waitfor()" as analternative to this method when it doesn't do what you want, e.g. theremote 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 currentsettings 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 erroris generated when a read causes the buffer to exceed this limit. Thedefault value is 1,048,576 bytes (1 MiB). The input buffer can growmuch larger than the block size when you continuously read using"getline()" or "waitfor()" and the data stream contains no newlinesor matching waitfor patterns.

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

A warning is printed to STDERR when attempting to set this attributeto 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,]                     [Family      => $family,]                     [Errmode     => $mode,]                     [Timeout     => $secs,]                     [Localhost   => $host,]                     [Localfamily => $family,]);

This method opens a TCP connection to $port on $host for the IPaddress $family. If any of those arguments are missing then thecurrent attribute value for the object is used. Specifing Hostsets that attribute for the object. Specifing any of the otheroptional named parameters overrides the current setting.

The default IP address family is "ipv4". $family may be set to"ipv4", "ipv6", or "any". See "family()" for more details.

Localhost is used to bind to a specific local network interface.

If the object is already open, it is closed before attempting aconnection.

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

Time-outs don't work for this method on machines that don't implementSIGALRM - most notably MS-Windows machines. For those machines, anerror is returned when the system reaches its own time-out whiletrying to connect.

A side effect of this method is to reset the alarm interval associatedwith 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 offerto enable a TELNET option made by the remote side. If you're usingDo or Will to indicate a willingness to enable, then anotification callback must have already been defined by a prior callto "option_callback()". See "option_callback()" for details onreceiving enable/disable notification of a TELNET option.

You can give multiple Do, Dont, Will, or Wont argumentsfor different TELNET options in the same call to this method.

The following example describes the meaning of the named parameters.A TELNET option, such as "TELOPT_ECHO" used below, is an integerconstant that you can import from Net::Telnet. See the source in fileTelnet.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 ordisable 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 is called when aTELNET option is enabled or disabled. Once defined, theoption_callback may not be undefined. However, calling this methodwith a different $coderef changes it.

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

Here are the circumstances that invoke $coderef:

*
An option becomes enabled because the remote side requested an enableand "option_accept()" had been used to arrange that it be accepted.
*
The remote side arbitrarily decides to disable an option that iscurrently enabled. Note that Net::Telnet always accepts a request todisable from the remote side.
*
"option_send()" was used to send a request to enable or disable anoption and the response from the remote side has just been received.Note, that if a request to enable is rejected then $coderef isstill 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 constantsfor the various TELNET options which just equate to an integer.
*
3. $is_remote is a boolean indicating for which side the optionapplies.
*
4. $is_enabled is a boolean indicating the option is enabled ordisabled
*
5. $was_enabled is a boolean indicating the option was previouslyenabled or disabled
*
6. $buf_position is an integer indicating the position in theobject'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 sentor received. This is useful for debugging when you send options via"option_send()" or you arrange to accept option requests from theremote side via "option_accept()". Also see "dump_log()".

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

To stop logging, use an empty string as an argument. The stoppedfilehandle is not closed.

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, thefilename is opened for logging and a filehandle to it is returned. Ifthe filehandle is not already opened or the filename can't be openedfor 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 version.

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 stateof 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 thisoption on the remote side.
*
$hashref->{remote_state}
*
string used to hold the internal state of option negotiation for thisoption 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 thisoption on the local side.
*
$hashref->{local_state}
*
string used to hold the internal state of option negotiation for thisoption 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 separatedfields you specify. Set this to specify what's printed betweenfields.

With no argument this method returns the current output fieldseparator set in the object. With an argument it sets the outputfield 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 whendebugging. Also see "dump_log()". Because most command interpretersecho back commands received, it's likely all your output would also bein an input log. See "input_log()". Note that output logging occursbefore newline translation. See "binmode()" for details on newlinetranslation.

If no argument is given, the log filehandle is returned. A returnedempty string indicates logging is off.

To stop logging, use an empty string as an argument. The stoppedfilehandle is not closed.

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, thefilename is opened for logging and a filehandle to it is returned. Ifthe filehandle is not already opened or the filename can't be openedfor 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'sno need to append all your commands with a newline. To avoid printingthe output_record_separator use "put()" or set theoutput_record_separator to an empty string.

With no argument this method returns the current output recordseparator set in the object. With an argument it sets the outputrecord separator to $chars and returns the previous value.

peerhost - IP address of the other end of the socket connection
    $ipaddr = $obj->peerhost;

This method returns a string which is the IPv4 or IPv6 address theremote socket is bound to (i.e. it is the IP address of "host()").It returns "" when not connected.

peerport - TCP port of the other end of the socket connection
    $port = $obj->peerport;

This method returns the port number which the remote socket is boundto. It is the same as the "port()" number when connected. Itreturns "" when not connected.

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

This method designates the remote TCP port for "open()". With noargument this method returns the current port number. With anargument it sets the current port number to $port and returns theprevious port. If $port is a TCP service name, then it's firstconverted to a port number using the perl function "getservbyname()".

The default value is 23.

The error mode action is performed when attempting to set thisattribute to something that is not a positive integer or a valid TCPservice name.

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

This method writes @list followed by the output_record_separatorto the open object and returns 1 if all data was successfullywritten. On time-out or other failures, the error mode action isperformed. See "errmode()".

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

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

You may also use the output field separator to print a string betweenthe 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 mostrecent "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 inputstream. It must be a string representing a valid perl pattern matchoperator. The methods "login()" and "cmd()" try to read untilmatching the prompt. They will fail with a time-out error if thepattern 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 theprevious 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 likefile 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 anchormetacharacters "^" and "$" refer to positions in the input buffer.

The error mode action is performed when attempting to set thisattribute 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 ifall 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 modeaction is performed. See "errmode()".

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

Optional named parameters are provided to override the currentsettings 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()".

sockfamily - IP address family of connected local socket
    $sockfamily = $obj->sockfamily;

This method returns which IP address family "open()" used tosuccessfully connect. It is most useful when the requested address"family()" for "open()" was "any". Values returned may be"ipv4", "ipv6", or "" (when not connected).

sockhost - IP address of this end of the socket connection
    $ipaddr = $obj->sockhost;

This method returns a string which is the IPv4 or IPv6 address thelocal socket is bound to. It returns "" when not connected.

sockport - TCP port of this end of the socket connection
    $port = $obj->sockport;

This method returns the port number which the local socket is boundto. It returns "" when not connected.

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 streamare recognized and handled. The TELNET protocol uses certaincharacter sequences sent in the data stream to control the session.If the port you're connecting to isn't using the TELNET protocol, thenyou 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 thentelnet 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 methodtimed-out. Remember that timing-out is itself an error. To be ableto invoke "timed_out()" after a time-out error, you'd have to changethe default error mode to something other than "die". See"errmode()".

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

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

This method sets the timeout interval used when performing I/Oor connecting to a port. When a method doesn't complete within thetimeout interval then it's an error and the error mode action isperformed.

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

If $secs is 0 then time-out occurs if the data cannot beimmediately read or written. Use the undefined value to turn offtiming-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 theprevious value. The default timeout value is 10 seconds.

A warning is printed to STDERR when attempting to set this attributeto something that is 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 theinput stream. All the characters before and including the match areremoved from the input stream.

In a list context the characters before the match and the matchedcharacters are returned in $prematch and $match. In a scalarcontext, the matched characters and all characters before it arediscarded and 1 is returned on success. On time-out, eof, or otherfailures, for both list and scalar context, the error mode action isperformed. See "errmode()".

You can specify more than one pattern or string by simply providingmultiple Match and/or String named parameters. A $matchopmust 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 youdon't think it should.

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

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

Of course don't forget about regexp metacharacters like ".",