.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::Telnet 3pm" .TH Net::Telnet 3pm "2013-09-16" "perl v5.18.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::Telnet \- interact with TELNET port or other TCP ports .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\f(CW\*(C`use Net::Telnet ();\*(C'\fR .PP see \s-1METHODS\s0 or \s-1EXAMPLES\s0 sections below .SH "DESCRIPTION" .IX Header "DESCRIPTION" Net::Telnet allows you to make client connections to a \s-1TCP\s0 port and do network I/O, especially to a port using the \s-1TELNET\s0 protocol. Simple I/O methods such as print, get, and getline are provided. More sophisticated interactive features are provided because connecting to a \s-1TELNET\s0 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. IPv6 support is available when using perl 5.14 or later (see \f(CW\*(C`family()\*(C'\fR. .PP Other reasons to use this module than strictly with a \s-1TELNET\s0 port are: .IP "\(bu" 2 You're not familiar with sockets and you want a simple way to make client connections to \s-1TCP\s0 services. .IP "\(bu" 2 You want to be able to specify your own time-out while connecting, reading, or writing. .IP "\(bu" 2 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. .PP Here's an example that prints who's logged-on to a remote host. In addition to a username and password, you must also know the user's shell prompt, which for this example is \f(CW"bash$ "\fR .PP .Vb 7 \& use Net::Telnet (); \& $t = new Net::Telnet (Timeout => 10, \& Prompt => \*(Aq/bash\e$ $/\*(Aq); \& $t\->open($host); \& $t\->login($username, $passwd); \& @lines = $t\->cmd("who"); \& print @lines; .Ve .PP See the \fB\s-1EXAMPLES\s0\fR section below for more examples. .PP Usage questions should be directed to the perlmonks.org discussion group. Bugs can be viewed or reported at cpan.org on the Net::Telnet page. .SS "What To Know Before Using" .IX Subsection "What To Know Before Using" .IP "\(bu" 2 All output is flushed while all input is buffered. Each object contains its own input buffer. .IP "\(bu" 2 The output record separator for \f(CW\*(C`print()\*(C'\fR and \f(CW\*(C`cmd()\*(C'\fR is set to \&\f(CW"\en"\fR by default, so that you don't have to append all your commands with a newline. To avoid printing a trailing \f(CW"\en"\fR use \f(CW\*(C`put()\*(C'\fR or set the \fIoutput_record_separator\fR to \f(CW""\fR. .IP "\(bu" 2 The methods \f(CW\*(C`login()\*(C'\fR and \f(CW\*(C`cmd()\*(C'\fR use the \fIprompt\fR 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. .IP "\(bu" 2 Use a combination of \f(CW\*(C`print()\*(C'\fR and \f(CW\*(C`waitfor()\*(C'\fR as an alternative to \&\f(CW\*(C`login()\*(C'\fR or \f(CW\*(C`cmd()\*(C'\fR when they don't do what you want. .IP "\(bu" 2 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 \f(CW\*(C`errmode()\*(C'\fR method for more information. .IP "\(bu" 2 When constructing the match operator argument for \f(CW\*(C`prompt()\*(C'\fR or \&\f(CW\*(C`waitfor()\*(C'\fR, always use single quotes instead of double quotes to avoid unexpected backslash interpretation (e.g. \f(CW\*(Aq/bash\e$ $/\*(Aq\fR). If you're constructing a \s-1DOS\s0 like file path, you'll need to use four backslashes to represent one (e.g. \f(CW\*(Aq/c:\e\e\e\eusers\e\e\e\ebill>$/i\*(Aq\fR). .Sp Of course don't forget about regexp metacharacters like \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`[\*(C'\fR, or \&\f(CW\*(C`$\*(C'\fR. You'll only need a single backslash to quote them. The anchor metacharacters \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR 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 \f(CW\*(C`$\*(C'\fR anchor. That way the prompt will only match if it's the last thing read. .IP "\(bu" 2 In the input stream, each sequence of \fIcarriage return\fR and \fIline feed\fR (i.e. \f(CW"\e015\e012"\fR or \s-1CR LF\s0) is converted to \f(CW"\en"\fR. In the output stream, each occurrence of \f(CW"\en"\fR is converted to a sequence of \s-1CR LF. \s0 See \f(CW\*(C`binmode()\*(C'\fR to change the behavior. \s-1TCP\s0 protocols typically use the \s-1ASCII\s0 sequence, carriage return and line feed to designate a newline. .IP "\(bu" 2 Timing-out while making a connection is disabled for machines that don't support the \f(CW\*(C`alarm()\*(C'\fR function. Most notably these include MS-Windows machines. .IP "\(bu" 2 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. .Sp If you have the \s-1IO::\s0 libraries installed (they come standard with perl5.004 and later) then IO::Socket::INET is used as a base class, otherwise FileHandle is used. .SS "Debugging" .IX Subsection "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 expectations is to use \f(CW\*(C`input_log()\*(C'\fR or \f(CW\*(C`dump_log()\*(C'\fR. .PP \&\f(CW\*(C`dump_log()\*(C'\fR allows you to see the data being sent from the remote side before any translation is done, while \f(CW\*(C`input_log()\*(C'\fR shows you the results after translation. The translation includes converting end of line characters, removing and responding to \s-1TELNET\s0 protocol commands in the data stream. .SS "Style of Named Parameters" .IX Subsection "Style of Named Parameters" Two different styles of named parameters are supported. This document only shows the \s-1IO::\s0 style: .PP .Vb 1 \& Net::Telnet\->new(Timeout => 20); .Ve .PP however the dash-option style is also allowed: .PP .Vb 1 \& Net::Telnet\->new(\-timeout => 20); .Ve .SS "Connecting to a Remote MS-Windows Machine" .IX Subsection "Connecting to a Remote MS-Windows Machine" By default MS-Windows doesn't come with a \s-1TELNET\s0 server. However third party \s-1TELNET\s0 servers are available. Unfortunately many of these servers falsely claim to be a \s-1TELNET\s0 server. This is especially true of the so-called \*(L"Microsoft Telnet Server\*(R" that comes installed with some newer versions MS-Windows. .PP When a \s-1TELNET\s0 server first accepts a connection, it must use the \s-1ASCII\s0 control characters carriage-return and line-feed to start a new line (see \s-1RFC854\s0). A server like the \*(L"Microsoft Telnet Server\*(R" that doesn't do this, isn't a \s-1TELNET\s0 server. These servers send \s-1ANSI\s0 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. .PP Connecting Net::Telnet to one of these false \s-1TELNET\s0 servers makes your job of parsing command output very difficult. It's better to replace a false \s-1TELNET\s0 server with a real \s-1TELNET\s0 server. The better \s-1TELNET\s0 servers for MS-Windows allow you to avoid the \s-1ANSI\s0 escapes by turning off something some of them call \fIconsole mode\fR. .SH "METHODS" .IX Header "METHODS" In the calling sequences below, square brackets \fB[]\fR represent optional parameters. .IP "\fBnew\fR \- create a new Net::Telnet object" 4 .IX Item "new - create a new Net::Telnet object" .Vb 1 \& $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,]); .Ve .Sp This is the constructor for Net::Telnet objects. A new object is returned on success, the error mode action is performed on failure \- see \f(CW\*(C`errmode()\*(C'\fR. The optional arguments are short-cuts to methods of the same name. .Sp If the \fI\f(CI$host\fI\fR argument is given then the object is opened by connecting to \s-1TCP \s0\fI\f(CI$port\fI\fR on \fI\f(CI$host\fI\fR. Also see \f(CW\*(C`open()\*(C'\fR. The new object returned is given the following defaults in the absence of corresponding named parameters: .RS 4 .IP "\(bu" 4 The default \fIHost\fR is \f(CW"localhost"\fR .IP "\(bu" 4 The default \fIPort\fR is \f(CW23\fR .IP "\(bu" 4 The default \fIFamily\fR is \f(CW"ipv4"\fR .IP "\(bu" 4 The default \fIPrompt\fR is \f(CW\*(Aq/[\e$%#>] $/\*(Aq\fR .IP "\(bu" 4 The default \fITimeout\fR is \f(CW10\fR .IP "\(bu" 4 The default \fIErrmode\fR is \f(CW"die"\fR .IP "\(bu" 4 The default \fIOutput_record_separator\fR is \f(CW"\en"\fR. Note that \fIOrs\fR is synonymous with \fIOutput_record_separator\fR. .IP "\(bu" 4 The default \fIInput_record_separator\fR is \f(CW"\en"\fR. Note that \fIRs\fR is synonymous with \fIInput_record_separator\fR. .IP "\(bu" 4 The default \fIBinmode\fR is \f(CW0\fR, which means do newline translation. .IP "\(bu" 4 The default \fITelnetmode\fR is \f(CW1\fR, which means respond to \s-1TELNET\s0 commands in the data stream. .IP "\(bu" 4 The default \fICmd_remove_mode\fR is \f(CW"auto"\fR .IP "\(bu" 4 The defaults for \fIDump_log\fR, \fIInput_log\fR, \fIOption_log\fR, and \&\fIOutput_log\fR are \f(CW""\fR, which means that logging is turned-off. .IP "\(bu" 4 The default \fIMax_buffer_length\fR is \f(CW1048576\fR bytes, i.e. 1 MiB. .IP "\(bu" 4 The default \fIOutput_field_separator\fR is \f(CW""\fR. Note that \fIOfs\fR is synonymous with \fIOutput_field_separator\fR. .IP "\(bu" 4 The default \fILocalhost\fR is \f(CW""\fR .IP "\(bu" 4 The default \fILocalfamily\fR is \f(CW"ipv4"\fR .RE .RS 4 .RE .IP "\fBbinmode\fR \- toggle newline translation" 4 .IX Item "binmode - toggle newline translation" .Vb 1 \& $mode = $obj\->binmode; \& \& $prev = $obj\->binmode($mode); .Ve .Sp This method controls whether or not sequences of carriage returns and line feeds (\s-1CR LF\s0 or more specifically \f(CW"\e015\e012"\fR) are translated. By default they are translated (i.e. binmode is \f(CW0\fR). .Sp If no argument is given, the current mode is returned. .Sp If \fI\f(CI$mode\fI\fR is \f(CW1\fR then binmode is \fIon\fR and newline translation is not done. .Sp If \fI\f(CI$mode\fI\fR is \f(CW0\fR then binmode is \fIoff\fR and newline translation is done. In the input stream, each sequence of \s-1CR LF\s0 is converted to \&\f(CW"\en"\fR and in the output stream, each occurrence of \f(CW"\en"\fR is converted to a sequence of \s-1CR LF.\s0 .Sp 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. .IP "\fBbreak\fR \- send \s-1TELNET\s0 break character" 4 .IX Item "break - send TELNET break character" .Vb 1 \& $ok = $obj\->break; .Ve .Sp This method sends the \s-1TELNET\s0 break character. This character is provided because it's a signal outside the \s-1ASCII\s0 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. .Sp This method returns \f(CW1\fR on success, or performs the error mode action on failure. .IP "\fBbuffer\fR \- scalar reference to object's input buffer" 4 .IX Item "buffer - scalar reference to object's input buffer" .Vb 1 \& $ref = $obj\->buffer; .Ve .Sp This method returns a scalar reference to the input buffer for \&\fI\f(CI$obj\fI\fR. 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. .IP "\fBbuffer_empty\fR \- discard all data in object's input buffer" 4 .IX Item "buffer_empty - discard all data in object's input buffer" .Vb 1 \& $obj\->buffer_empty; .Ve .Sp This method removes all data in the input buffer for \fI\f(CI$obj\fI\fR. .IP "\fBclose\fR \- close object" 4 .IX Item "close - close object" .Vb 1 \& $ok = $obj\->close; .Ve .Sp This method closes the socket, file, or pipe associated with the object. It always returns a value of \f(CW1\fR. .IP "\fBcmd\fR \- issue command and retrieve output" 4 .IX Item "cmd - issue command and retrieve output" .Vb 11 \& $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,]); .Ve .Sp This method sends the command \fI\f(CI$string\fI\fR, 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. .Sp The command \fI\f(CI$string\fI\fR is automatically appended with the output_record_separator, by default it is \f(CW"\en"\fR. This is similar to someone typing a command and hitting the return key. Set the output_record_separator to change this behavior. .Sp In a scalar context, the characters read from the remote side are discarded and \f(CW1\fR is returned on success. On time-out, eof, or other failures, the error mode action is performed. See \f(CW\*(C`errmode()\*(C'\fR. .Sp 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 containing 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 \f(CW\*(C`errmode()\*(C'\fR. .Sp The characters that matched the prompt may be retrieved using \&\f(CW\*(C`last_prompt()\*(C'\fR. .Sp Many command interpreters echo back the command sent. In most situations, this method removes the first line returned from the remote side (i.e. the echoed back command). See \f(CW\*(C`cmd_remove_mode()\*(C'\fR for more control over this feature. .Sp Use \f(CW\*(C`dump_log()\*(C'\fR to debug when this method keeps timing-out and you don't think it should. .Sp Consider using a combination of \f(CW\*(C`print()\*(C'\fR and \f(CW\*(C`waitfor()\*(C'\fR as an alternative to this method when it doesn't do what you want, e.g. the command you send prompts for input. .Sp The \fIOutput\fR 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 referenced scalar. If you pass an array or hash reference, the lines of output are returned in the referenced array or hash. You can use \&\f(CW\*(C`input_record_separator()\*(C'\fR to change the notion of what separates a line. .Sp Optional named parameters are provided to override the current settings 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 output_record_separator. .IP "\fBcmd_remove_mode\fR \- toggle removal of echoed commands" 4 .IX Item "cmd_remove_mode - toggle removal of echoed commands" .Vb 1 \& $mode = $obj\->cmd_remove_mode; \& \& $prev = $obj\->cmd_remove_mode($mode); .Ve .Sp This method controls how to deal with echoed back commands in the output returned by \fIcmd()\fR. 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 normally returned by \fIcmd()\fR. .Sp If no argument is given, the current mode is returned. .Sp If \fI\f(CI$mode\fI\fR is \f(CW0\fR then the command output returned from \fIcmd()\fR has no lines removed. If \fI\f(CI$mode\fI\fR is a positive integer, then the first \&\fI\f(CI$mode\fI\fR lines of command output are stripped. .Sp By default, \fI\f(CI$mode\fI\fR is set to \f(CW"auto"\fR. 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 \f(CW\*(C`option_accept()\*(C'\fR. .Sp A warning is printed to \s-1STDERR\s0 when attempting to set this attribute to something that is not \f(CW"auto"\fR or a non-negative integer. .IP "\fBdump_log\fR \- log all I/O in dump format" 4 .IX Item "dump_log - log all I/O in dump format" .Vb 1 \& $fh = $obj\->dump_log; \& \& $fh = $obj\->dump_log($fh); \& \& $fh = $obj\->dump_log($filename); .Ve .Sp This method starts or stops dump format logging of all the object's input and output. The dump format shows the blocks read and written in a hexadecimal and printable character format. This method is useful when debugging, however you might want to first try \&\f(CW\*(C`input_log()\*(C'\fR as it's more readable. .Sp If no argument is given, the log filehandle is returned. A returned empty string indicates logging is off. .Sp To stop logging, use an empty string as an argument. The stopped filehandle is not closed. .Sp 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 filename is opened for logging and a filehandle to it is returned. If the filehandle is not already opened or the filename can't be opened for writing, the error mode action is performed. .IP "\fBeof\fR \- end of file indicator" 4 .IX Item "eof - end of file indicator" .Vb 1 \& $eof = $obj\->eof; .Ve .Sp This method returns \f(CW1\fR 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 \fI\f(CI$obj\fI\fR has closed. In other words \fI\f(CI$obj\fI\fR 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. .IP "\fBerrmode\fR \- define action to be performed on error" 4 .IX Item "errmode - define action to be performed on error" .Vb 1 \& $mode = $obj\->errmode; \& \& $prev = $obj\->errmode($mode); .Ve .Sp This method gets or sets the action used when errors are encountered using the object. The first calling sequence returns the current error mode. The second calling sequence sets it to \fI\f(CI$mode\fI\fR and returns the previous mode. Valid values for \fI\f(CI$mode\fI\fR are \f(CW"die"\fR (the default), \f(CW"return"\fR, a \fIcoderef\fR, or an \fIarrayref\fR. .Sp When mode is \f(CW"die"\fR and an error is encountered using the object, then an error message is printed to standard error and the program dies. .Sp When mode is \f(CW"return"\fR 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 message may be obtained using \f(CW\*(C`errmsg()\*(C'\fR. .Sp When mode is a \fIcoderef\fR, then when an error is encountered \&\fIcoderef\fR is called with the error message as its first argument. Using this mode you may have your own subroutine handle errors. If \&\fIcoderef\fR itself returns then the method generating the error returns undefined or an empty list depending on context. .Sp When mode is an \fIarrayref\fR, the first element of the array must be a \&\fIcoderef\fR. Any elements that follow are the arguments to \fIcoderef\fR. When an error is encountered, the \fIcoderef\fR is called with its arguments. Using this mode you may have your own subroutine handle errors. If the \fIcoderef\fR itself returns then the method generating the error returns undefined or an empty list depending on context. .Sp A warning is printed to \s-1STDERR\s0 when attempting to set this attribute to something that is not \f(CW"die"\fR, \f(CW"return"\fR, a \fIcoderef\fR, or an \&\fIarrayref\fR whose first element isn't a \fIcoderef\fR. .IP "\fBerrmsg\fR \- most recent error message" 4 .IX Item "errmsg - most recent error message" .Vb 1 \& $msg = $obj\->errmsg; \& \& $prev = $obj\->errmsg(@msgs); .Ve .Sp 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 message for the object to the concatenation of \fI\f(CI@msgs\fI\fR and returns the previous error message. Normally, error messages are set internally by a method when an error is encountered. .IP "\fBerror\fR \- perform the error mode action" 4 .IX Item "error - perform the error mode action" .Vb 1 \& $obj\->error(@msgs); .Ve .Sp This method concatenates \fI\f(CI@msgs\fI\fR into a string and places it in the object as the error message. Also see \f(CW\*(C`errmsg()\*(C'\fR. It then performs the error mode action. Also see \f(CW\*(C`errmode()\*(C'\fR. .Sp If the error mode doesn't cause the program to die, then an undefined value or an empty list is returned depending on the context. .Sp This method is primarily used by this class or a sub-class to perform the user requested action when an error is encountered. .IP "\fBfamily\fR \- \s-1IP\s0 address family for remote host" 4 .IX Item "family - IP address family for remote host" .Vb 1 \& $family = $obj\->family; \& \& $prev = $obj\->family($family); .Ve .Sp This method designates which \s-1IP\s0 address family \f(CW\*(C`host()\*(C'\fR refers to, i.e. IPv4 or IPv6. IPv6 support is available when using perl 5.14 or later. With no argument it returns the current value set in the object. With an argument it sets the current address family to \&\fI\f(CI$family\fI\fR and returns the previous address family. Valid values are \&\f(CW"ipv4"\fR, \f(CW"ipv6"\fR, or \f(CW"any"\fR. When \f(CW"any"\fR, the \f(CW\*(C`host()\*(C'\fR can be a hostname or \s-1IP\s0 address for either IPv4 or IPv6. After connecting, you can use \f(CW\*(C`sockfamily()\*(C'\fR to determine which \s-1IP\s0 address family was used. .Sp The default value is \f(CW"ipv4"\fR. .Sp The error mode action is performed when attempting to set this attribute to something that isn't \f(CW"ipv4"\fR, \f(CW"ipv6"\fR, or \f(CW"any"\fR. It is also performed when attempting to set it to \f(CW"ipv6"\fR when the Socket module is less than version 1.94 or IPv6 is not supported in the \s-1OS\s0 as indicated by Socket::AF_INET6 not being defined. .IP "\fBfhopen\fR \- use already open filehandle for I/O" 4 .IX Item "fhopen - use already open filehandle for I/O" .Vb 1 \& $ok = $obj\->fhopen($fh); .Ve .Sp This method associates the open filehandle \fI\f(CI$fh\fI\fR with \fI\f(CI$obj\fI\fR for further I/O. Filehandle \fI\f(CI$fh\fI\fR must already be opened. .Sp Suppose you want to use the features of this module to do I/O to something other than a \s-1TCP\s0 port, for example \s-1STDIN\s0 or a filehandle opened to read from a process. Instead of opening the object for I/O to a \s-1TCP\s0 port by using \f(CW\*(C`open()\*(C'\fR or \f(CW\*(C`new()\*(C'\fR, call this method instead. .Sp The value \f(CW1\fR is returned success, the error mode action is performed on failure. .IP "\fBget\fR \- read block of data" 4 .IX Item "get - read block of data" .Vb 4 \& $data = $obj\->get([Binmode => $mode,] \& [Errmode => $errmode,] \& [Telnetmode => $mode,] \& [Timeout => $secs,]); .Ve .Sp 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 \fI\f(CI$secs\fI\fR. Also see \&\f(CW\*(C`timeout()\*(C'\fR. If buffered data is available to return, it also checks for a block of data that can be immediately read. .Sp On eof an undefined value is returned. On time-out or other failures, the error mode action is performed. To distinguish between eof or an error occurring when the error mode is not set to \f(CW"die"\fR, use \&\f(CW\*(C`eof()\*(C'\fR. .Sp Optional named parameters are provided to override the current settings of binmode, errmode, telnetmode, and timeout. .IP "\fBgetline\fR \- read next line" 4 .IX Item "getline - read next line" .Vb 6 \& $line = $obj\->getline([Binmode => $mode,] \& [Errmode => $errmode,] \& [Input_record_separator => $chars,] \& [Rs => $chars,] \& [Telnetmode => $mode,] \& [Timeout => $secs,]); .Ve .Sp This method reads and returns the next line of data from the object. You can use \f(CW\*(C`input_record_separator()\*(C'\fR to change the notion of what separates a line. The default is \f(CW"\en"\fR. If a line isn't immediately available, this method blocks waiting for a line or a time-out. .Sp On eof an undefined value is returned. On time-out or other failures, the error mode action is performed. To distinguish between eof or an error occurring when the error mode is not set to \f(CW"die"\fR, use \&\f(CW\*(C`eof()\*(C'\fR. .Sp Optional named parameters are provided to override the current settings of binmode, errmode, input_record_separator, rs, telnetmode, and timeout. Rs is synonymous with input_record_separator. .IP "\fBgetlines\fR \- read next lines" 4 .IX Item "getlines - read next lines" .Vb 7 \& @lines = $obj\->getlines([Binmode => $mode,] \& [Errmode => $errmode,] \& [Input_record_separator => $chars,] \& [Rs => $chars,] \& [Telnetmode => $mode,] \& [Timeout => $secs,] \& [All => $boolean,]); .Ve .Sp This method reads and returns all the lines of data from the object until end of file is read. You can use \f(CW\*(C`input_record_separator()\*(C'\fR to change the notion of what separates a line. The default is \f(CW"\en"\fR. A time-out error occurs if all the lines can't be read within the time-out interval. See \f(CW\*(C`timeout()\*(C'\fR. .Sp 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 parameter \&\fIAll\fR and set \fI\f(CI$boolean\fI\fR to \f(CW""\fR or \f(CW0\fR. .Sp If only eof is read then an empty list is returned. On time-out or other failures, the error mode action is performed. Use \f(CW\*(C`eof()\*(C'\fR to distinguish between reading only eof or an error occurring when the error mode is not set to \f(CW"die"\fR. .Sp Optional named parameters are provided to override the current settings of binmode, errmode, input_record_separator, rs, telnetmode, and timeout. Rs is synonymous with input_record_separator. .IP "\fBhost\fR \- name or \s-1IP\s0 address of remote host" 4 .IX Item "host - name or IP address of remote host" .Vb 1 \& $host = $obj\->host; \& \& $prev = $obj\->host($host); .Ve .Sp This method designates the remote host for \f(CW\*(C`open()\*(C'\fR. It is either a hostname or an \s-1IP\s0 address. With no argument it returns the current value set in the object. With an argument it sets the current host name to \fI\f(CI$host\fI\fR and returns the previous value. Use \f(CW\*(C`family()\*(C'\fR to control which \s-1IP\s0 address family, IPv4 or IPv6, host refers to. .Sp The default value is \f(CW"localhost"\fR. It may also be set by \f(CW\*(C`open()\*(C'\fR or \f(CW\*(C`new()\*(C'\fR. .IP "\fBinput_log\fR \- log all input" 4 .IX Item "input_log - log all input" .Vb 1 \& $fh = $obj\->input_log; \& \& $fh = $obj\->input_log($fh); \& \& $fh = $obj\->input_log($filename); .Ve .Sp This method starts or stops logging of input. This is useful when debugging. Also see \f(CW\*(C`dump_log()\*(C'\fR. Because most command interpreters 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 \f(CW\*(C`binmode()\*(C'\fR for details on newline translation. .Sp If no argument is given, the log filehandle is returned. A returned empty string indicates logging is off. .Sp To stop logging, use an empty string as an argument. The stopped filehandle is not closed. .Sp 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 filename is opened for logging and a filehandle to it is returned. If the filehandle is not already opened or the filename can't be opened for writing, the error mode action is performed. .IP "\fBinput_record_separator\fR \- input line delimiter" 4 .IX Item "input_record_separator - input line delimiter" .Vb 1 \& $chars = $obj\->input_record_separator; \& \& $prev = $obj\->input_record_separator($chars); .Ve .Sp This method designates the line delimiter for input. It's used with \&\f(CW\*(C`getline()\*(C'\fR, \f(CW\*(C`getlines()\*(C'\fR, and \f(CW\*(C`cmd()\*(C'\fR to determine lines in the input. .Sp With no argument this method returns the current input record separator set in the object. With an argument it sets the input record separator to \fI\f(CI$chars\fI\fR and returns the previous value. Note that \fI\f(CI$chars\fI\fR must have length. .Sp A warning is printed to \s-1STDERR\s0 when attempting to set this attribute to a string with no length. .IP "\fBlast_prompt\fR \- last prompt read" 4 .IX Item "last_prompt - last prompt read" .Vb 1 \& $string = $obj\->last_prompt; \& \& $prev = $obj\->last_prompt($string); .Ve .Sp With no argument this method returns the last prompt read by \fIcmd()\fR or \&\fIlogin()\fR. See \f(CW\*(C`prompt()\*(C'\fR. With an argument it sets the last prompt read to \fI\f(CI$string\fI\fR and returns the previous value. Normally, only internal methods set the last prompt. .IP "\fBlastline\fR \- last line read" 4 .IX Item "lastline - last line read" .Vb 1 \& $line = $obj\->lastline; \& \& $prev = $obj\->lastline($line); .Ve .Sp 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 message before closing. .Sp With no argument this method returns the last line read from the object. With an argument it sets the last line read to \fI\f(CI$line\fI\fR and returns the previous value. Normally, only internal methods set the last line. .IP "\fBlocalfamily\fR \- \s-1IP\s0 address family for local host" 4 .IX Item "localfamily - IP address family for local host" .Vb 1 \& $localfamily = $obj\->localfamily; \& \& $prev = $obj\->localfamily($family); .Ve .Sp This method designates which \s-1IP\s0 address family \f(CW\*(C`localhost()\*(C'\fR refers to, i.e. IPv4 or IPv6. IPv6 support is available when using perl 5.14 or later. With no argument it returns the current value set in the object. With an argument it sets the current local address family to \&\fI\f(CI$family\fI\fR and returns the previous address family. Valid values are \f(CW"ipv4"\fR, \f(CW"ipv6"\fR, or \f(CW"any"\fR. When \f(CW"any"\fR, the \&\f(CW\*(C`localhost()\*(C'\fR can be a hostname or \s-1IP\s0 address for either IPv4 or IPv6. .Sp The default value is \f(CW"ipv4"\fR. .Sp The error mode action is performed when attempting to set this attribute to something that isn't \f(CW"ipv4"\fR, \f(CW"ipv6"\fR, or \f(CW"any"\fR. It is also performed when attempting to set it to \f(CW"ipv6"\fR when the Socket module is less than version 1.94 or IPv6 is not supported in the \s-1OS\s0 as indicated by Socket::AF_INET6 not being defined. .IP "\fBlocalhost\fR \- bind local socket to a specific network interface" 4 .IX Item "localhost - bind local socket to a specific network interface" .Vb 1 \& $localhost = $obj\->localhost; \& \& $prev = $obj\->localhost($host); .Ve .Sp This method designates the local socket \s-1IP\s0 address for \f(CW\*(C`open()\*(C'\fR. It is either a hostname, an \s-1IP\s0 address, or a null string (i.e. \f(CW""\fR). A null string disables this feature. .Sp Normally the \s-1OS\s0 picks which local network interface to use. This method is useful when the local machine has more than one network interface and you want to bind to a specific one. With no argument it returns the current value set in the object. With an argument it sets the current local host name to \fI\f(CI$host\fI\fR and returns the previous value. Use \f(CW\*(C`localfamily()\*(C'\fR to control which \s-1IP\s0 address family, IPv4 or IPv6, local host refers to. .Sp The default value is \f(CW""\fR. .IP "\fBlogin\fR \- perform standard login" 4 .IX Item "login - perform standard login" .Vb 1 \& $ok = $obj\->login($username, $password); \& \& $ok = $obj\->login(Name => $username, \& Password => $password, \& [Errmode => $mode,] \& [Prompt => $match,] \& [Timeout => $secs,]); .Ve .Sp This method performs a standard login by waiting for a login prompt and responding with \fI\f(CI$username\fI\fR, then waiting for the password prompt and responding with \fI\f(CI$password\fI\fR, 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. .Sp Login prompt must match either of these case insensitive patterns: .Sp .Vb 2 \& /login[: ]*$/i \& /username[: ]*$/i .Ve .Sp Password prompt must match this case insensitive pattern: .Sp .Vb 1 \& /password[: ]*$/i .Ve .Sp The command interpreter prompt must match the current setting of prompt. See \f(CW\*(C`prompt()\*(C'\fR. .Sp Use \f(CW\*(C`dump_log()\*(C'\fR to debug when this method keeps timing-out and you don't think it should. .Sp Consider using a combination of \f(CW\*(C`print()\*(C'\fR and \f(CW\*(C`waitfor()\*(C'\fR 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. .Sp On success, \f(CW1\fR is returned. On time out, eof, or other failures, the error mode action is performed. See \f(CW\*(C`errmode()\*(C'\fR. .Sp Optional named parameters are provided to override the current settings of errmode, prompt, and timeout. .IP "\fBmax_buffer_length\fR \- maximum size of input buffer" 4 .IX Item "max_buffer_length - maximum size of input buffer" .Vb 1 \& $len = $obj\->max_buffer_length; \& \& $prev = $obj\->max_buffer_length($len); .Ve .Sp 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 (1 MiB). The input buffer can grow much larger than the block size when you continuously read using \&\f(CW\*(C`getline()\*(C'\fR or \f(CW\*(C`waitfor()\*(C'\fR and the data stream contains no newlines or matching waitfor patterns. .Sp 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 \fI\f(CI$len\fI\fR and returns the previous value. Values of \fI\f(CI$len\fI\fR smaller than 512 will be adjusted to 512. .Sp A warning is printed to \s-1STDERR\s0 when attempting to set this attribute to something that isn't a positive integer. .IP "\fBofs\fR \- field separator for print" 4 .IX Item "ofs - field separator for print" .Vb 1 \& $chars = $obj\->ofs \& \& $prev = $obj\->ofs($chars); .Ve .Sp This method is synonymous with \f(CW\*(C`output_field_separator()\*(C'\fR. .IP "\fBopen\fR \- connect to port on remote host" 4 .IX Item "open - connect to port on remote host" .Vb 1 \& $ok = $obj\->open($host); \& \& $ok = $obj\->open([Host => $host,] \& [Port => $port,] \& [Family => $family,] \& [Errmode => $mode,] \& [Timeout => $secs,] \& [Localhost => $host,] \& [Localfamily => $family,]); .Ve .Sp This method opens a \s-1TCP\s0 connection to \fI\f(CI$port\fI\fR on \fI\f(CI$host\fI\fR for the \s-1IP\s0 address \fI\f(CI$family\fI\fR. If any of those arguments are missing then the current attribute value for the object is used. Specifying \fIHost\fR sets that attribute for the object. Specifying any of the other optional named parameters overrides the current setting. .Sp The default \s-1IP\s0 address family is \f(CW"ipv4"\fR. \fI\f(CI$family\fI\fR may be set to \&\f(CW"ipv4"\fR, \f(CW"ipv6"\fR, or \f(CW"any"\fR. See \f(CW\*(C`family()\*(C'\fR for more details. .Sp \&\fILocalhost\fR is used to bind to a specific local network interface. .Sp If the object is already open, it is closed before attempting a connection. .Sp On success \f(CW1\fR is returned. On time-out or other connection failures, the error mode action is performed. See \f(CW\*(C`errmode()\*(C'\fR. .Sp Time-outs don't work for this method on machines that don't implement \&\s-1SIGALRM \-\s0 most notably MS-Windows machines. For those machines, an error is returned when the system reaches its own time-out while trying to connect. .Sp A side effect of this method is to reset the alarm interval associated with \s-1SIGALRM.\s0 .IP "\fBoption_accept\fR \- indicate willingness to accept a \s-1TELNET\s0 option" 4 .IX Item "option_accept - indicate willingness to accept a TELNET option" .Vb 4 \& $fh = $obj\->option_accept([Do => $telopt,] \& [Dont => $telopt,] \& [Will => $telopt,] \& [Wont => $telopt,]); .Ve .Sp This method is used to indicate whether to accept or reject an offer to enable a \s-1TELNET\s0 option made by the remote side. If you're using \&\fIDo\fR or \fIWill\fR to indicate a willingness to enable, then a notification callback must have already been defined by a prior call to \f(CW\*(C`option_callback()\*(C'\fR. See \f(CW\*(C`option_callback()\*(C'\fR for details on receiving enable/disable notification of a \s-1TELNET\s0 option. .Sp You can give multiple \fIDo\fR, \fIDont\fR, \fIWill\fR, or \fIWont\fR arguments for different \s-1TELNET\s0 options in the same call to this method. .Sp The following example describes the meaning of the named parameters. A \s-1TELNET\s0 option, such as \f(CW\*(C`TELOPT_ECHO\*(C'\fR used below, is an integer constant that you can import from Net::Telnet. See the source in file Telnet.pm for the complete list. .RS 4 .IP "\(bu" 4 \&\fIDo\fR => \f(CW\*(C`TELOPT_ECHO\*(C'\fR .RS 4 .IP "\(bu" 4 we'll accept an offer to enable the echo option on the local side .RE .RS 4 .RE .IP "\(bu" 4 \&\fIDont\fR => \f(CW\*(C`TELOPT_ECHO\*(C'\fR .RS 4 .IP "\(bu" 4 we'll reject an offer to enable the echo option on the local side .RE .RS 4 .RE .IP "\(bu" 4 \&\fIWill\fR => \f(CW\*(C`TELOPT_ECHO\*(C'\fR .RS 4 .IP "\(bu" 4 we'll accept an offer to enable the echo option on the remote side .RE .RS 4 .RE .IP "\(bu" 4 \&\fIWont\fR => \f(CW\*(C`TELOPT_ECHO\*(C'\fR .RS 4 .IP "\(bu" 4 we'll reject an offer to enable the echo option on the remote side .RE .RS 4 .RE .IP "\(bu" 4 Use \f(CW\*(C`option_send()\*(C'\fR to send a request to the remote side to enable or disable a particular \s-1TELNET\s0 option. .RE .RS 4 .RE .IP "\fBoption_callback\fR \- define the option negotiation callback" 4 .IX Item "option_callback - define the option negotiation callback" .Vb 1 \& $coderef = $obj\->option_callback; \& \& $prev = $obj\->option_callback($coderef); .Ve .Sp This method defines the callback subroutine that is called when a \&\s-1TELNET\s0 option is enabled or disabled. Once defined, the \&\fIoption_callback\fR may not be undefined. However, calling this method with a different \fI\f(CI$coderef\fI\fR changes it. .Sp A warning is printed to \s-1STDERR\s0 when attempting to set this attribute to something that isn't a coderef. .Sp Here are the circumstances that invoke \fI\f(CI$coderef\fI\fR: .RS 4 .IP "\(bu" 4 An option becomes enabled because the remote side requested an enable and \f(CW\*(C`option_accept()\*(C'\fR had been used to arrange that it be accepted. .IP "\(bu" 4 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. .IP "\(bu" 4 \&\f(CW\*(C`option_send()\*(C'\fR 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 \fI\f(CI$coderef\fI\fR is still invoked even though the option didn't change. .IP "\(bu" 4 Here are the arguments passed to \fI&$coderef\fR: .Sp .Vb 2 \& &$coderef($obj, $option, $is_remote, \& $is_enabled, $was_enabled, $buf_position); .Ve .RE .RS 4 .IP "\(bu" 4 1. \fI\f(CI$obj\fI\fR is the Net::Telnet object .IP "\(bu" 4 2. \fI\f(CI$option\fI\fR is the \s-1TELNET\s0 option. Net::Telnet exports constants for the various \s-1TELNET\s0 options which just equate to an integer. .IP "\(bu" 4 3. \fI\f(CI$is_remote\fI\fR is a boolean indicating for which side the option applies. .IP "\(bu" 4 4. \fI\f(CI$is_enabled\fI\fR is a boolean indicating the option is enabled or disabled .IP "\(bu" 4 5. \fI\f(CI$was_enabled\fI\fR is a boolean indicating the option was previously enabled or disabled .IP "\(bu" 4 6. \fI\f(CI$buf_position\fI\fR is an integer indicating the position in the object's input buffer where the option takes effect. See \f(CW\*(C`buffer()\*(C'\fR to access the object's input buffer. .RE .RS 4 .RE .IP "\fBoption_log\fR \- log all \s-1TELNET\s0 options sent or received" 4 .IX Item "option_log - log all TELNET options sent or received" .Vb 1 \& $fh = $obj\->option_log; \& \& $fh = $obj\->option_log($fh); \& \& $fh = $obj\->option_log($filename); .Ve .Sp This method starts or stops logging of all \s-1TELNET\s0 options being sent or received. This is useful for debugging when you send options via \&\f(CW\*(C`option_send()\*(C'\fR or you arrange to accept option requests from the remote side via \f(CW\*(C`option_accept()\*(C'\fR. Also see \f(CW\*(C`dump_log()\*(C'\fR. .Sp If no argument is given, the log filehandle is returned. An empty string indicates logging is off. .Sp To stop logging, use an empty string as an argument. The stopped filehandle is not closed. .Sp 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 filename is opened for logging and a filehandle to it is returned. If the filehandle is not already opened or the filename can't be opened for writing, the error mode action is performed. .IP "\fBoption_send\fR \- send \s-1TELNET\s0 option negotiation request" 4 .IX Item "option_send - send TELNET option negotiation request" .Vb 5 \& $ok = $obj\->option_send([Do => $telopt,] \& [Dont => $telopt,] \& [Will => $telopt,] \& [Wont => $telopt,] \& [Async => $boolean,]); .Ve .Sp This method is not yet implemented. Look for it in a future version. .IP "\fBoption_state\fR \- get current state of a \s-1TELNET\s0 option" 4 .IX Item "option_state - get current state of a TELNET option" .Vb 1 \& $hashref = $obj\->option_state($telopt); .Ve .Sp This method returns a hashref containing a copy of the current state of \s-1TELNET\s0 option \fI\f(CI$telopt\fI\fR. .Sp Here are the values returned in the hash: .RS 4 .IP "\(bu" 4 \&\fI\f(CI$hashref\fI\fR\->{remote_enabled} .RS 4 .IP "\(bu" 4 boolean that indicates if the option is enabled on the remote side. .RE .RS 4 .RE .IP "\(bu" 4 \&\fI\f(CI$hashref\fI\fR\->{remote_enable_ok} .RS 4 .IP "\(bu" 4 boolean that indicates if it's ok to accept an offer to enable this option on the remote side. .RE .RS 4 .RE .IP "\(bu" 4 \&\fI\f(CI$hashref\fI\fR\->{remote_state} .RS 4 .IP "\(bu" 4 string used to hold the internal state of option negotiation for this option on the remote side. .RE .RS 4 .RE .IP "\(bu" 4 \&\fI\f(CI$hashref\fI\fR\->{local_enabled} .RS 4 .IP "\(bu" 4 boolean that indicates if the option is enabled on the local side. .RE .RS 4 .RE .IP "\(bu" 4 \&\fI\f(CI$hashref\fI\fR\->{local_enable_ok} .RS 4 .IP "\(bu" 4 boolean that indicates if it's ok to accept an offer to enable this option on the local side. .RE .RS 4 .RE .IP "\(bu" 4 \&\fI\f(CI$hashref\fI\fR\->{local_state} .RS 4 .IP "\(bu" 4 string used to hold the internal state of option negotiation for this option on the local side. .RE .RS 4 .RE .RE .RS 4 .RE .IP "\fBors\fR \- output line delimiter" 4 .IX Item "ors - output line delimiter" .Vb 1 \& $chars = $obj\->ors; \& \& $prev = $obj\->ors($chars); .Ve .Sp This method is synonymous with \f(CW\*(C`output_record_separator()\*(C'\fR. .IP "\fBoutput_field_separator\fR \- field separator for print" 4 .IX Item "output_field_separator - field separator for print" .Vb 1 \& $chars = $obj\->output_field_separator; \& \& $prev = $obj\->output_field_separator($chars); .Ve .Sp This method designates the output field separator for \f(CW\*(C`print()\*(C'\fR. Ordinarily the print method simply prints out the comma separated fields you specify. Set this to specify what's printed between fields. .Sp With no argument this method returns the current output field separator set in the object. With an argument it sets the output field separator to \fI\f(CI$chars\fI\fR and returns the previous value. .Sp By default it's set to an empty string. .IP "\fBoutput_log\fR \- log all output" 4 .IX Item "output_log - log all output" .Vb 1 \& $fh = $obj\->output_log; \& \& $fh = $obj\->output_log($fh); \& \& $fh = $obj\->output_log($filename); .Ve .Sp This method starts or stops logging of output. This is useful when debugging. Also see \f(CW\*(C`dump_log()\*(C'\fR. Because most command interpreters echo back commands received, it's likely all your output would also be in an input log. See \f(CW\*(C`input_log()\*(C'\fR. Note that output logging occurs before newline translation. See \f(CW\*(C`binmode()\*(C'\fR for details on newline translation. .Sp If no argument is given, the log filehandle is returned. A returned empty string indicates logging is off. .Sp To stop logging, use an empty string as an argument. The stopped filehandle is not closed. .Sp 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 filename is opened for logging and a filehandle to it is returned. If the filehandle is not already opened or the filename can't be opened for writing, the error mode action is performed. .IP "\fBoutput_record_separator\fR \- output line delimiter" 4 .IX Item "output_record_separator - output line delimiter" .Vb 1 \& $chars = $obj\->output_record_separator; \& \& $prev = $obj\->output_record_separator($chars); .Ve .Sp This method designates the output line delimiter for \f(CW\*(C`print()\*(C'\fR and \&\f(CW\*(C`cmd()\*(C'\fR. Set this to specify what's printed at the end of \f(CW\*(C`print()\*(C'\fR and \f(CW\*(C`cmd()\*(C'\fR. .Sp The output record separator is set to \f(CW"\en"\fR by default, so there's no need to append all your commands with a newline. To avoid printing the output_record_separator use \f(CW\*(C`put()\*(C'\fR or set the output_record_separator to an empty string. .Sp With no argument this method returns the current output record separator set in the object. With an argument it sets the output record separator to \fI\f(CI$chars\fI\fR and returns the previous value. .IP "\fBpeerhost\fR \- \s-1IP\s0 address of the other end of the socket connection" 4 .IX Item "peerhost - IP address of the other end of the socket connection" .Vb 1 \& $ipaddr = $obj\->peerhost; .Ve .Sp This method returns a string which is the IPv4 or IPv6 address the remote socket is bound to (i.e. it is the \s-1IP\s0 address of \f(CW\*(C`host()\*(C'\fR). It returns \f(CW""\fR when not connected. .IP "\fBpeerport\fR \- \s-1TCP\s0 port of the other end of the socket connection" 4 .IX Item "peerport - TCP port of the other end of the socket connection" .Vb 1 \& $port = $obj\->peerport; .Ve .Sp This method returns the port number which the remote socket is bound to. It is the same as the \f(CW\*(C`port()\*(C'\fR number when connected. It returns \f(CW""\fR when not connected. .IP "\fBport\fR \- remote port" 4 .IX Item "port - remote port" .Vb 1 \& $port = $obj\->port; \& \& $prev = $obj\->port($port); .Ve .Sp This method designates the remote \s-1TCP\s0 port for \f(CW\*(C`open()\*(C'\fR. With no argument this method returns the current port number. With an argument it sets the current port number to \fI\f(CI$port\fI\fR and returns the previous port. If \fI\f(CI$port\fI\fR is a \s-1TCP\s0 service name, then it's first converted to a port number using the perl function \f(CW\*(C`getservbyname()\*(C'\fR. .Sp The default value is \f(CW23\fR. .Sp The error mode action is performed when attempting to set this attribute to something that is not a positive integer or a valid \s-1TCP\s0 service name. .IP "\fBprint\fR \- write to object" 4 .IX Item "print - write to object" .Vb 1 \& $ok = $obj\->print(@list); .Ve .Sp This method writes \fI\f(CI@list\fI\fR followed by the \fIoutput_record_separator\fR to the open object and returns \f(CW1\fR if all data was successfully written. On time-out or other failures, the error mode action is performed. See \f(CW\*(C`errmode()\*(C'\fR. .Sp By default, the \f(CW\*(C`output_record_separator()\*(C'\fR is set to \f(CW"\en"\fR 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 \&\f(CW"\en"\fR use \f(CW\*(C`put()\*(C'\fR instead or set the output_record_separator to an empty string. .Sp On failure, it's possible that some data was written. If you choose to try and recover from a print timing-out, use \f(CW\*(C`print_length()\*(C'\fR to determine how much was written before the error occurred. .Sp You may also use the output field separator to print a string between the list elements. See \f(CW\*(C`output_field_separator()\*(C'\fR. .IP "\fBprint_length\fR \- number of bytes written by print" 4 .IX Item "print_length - number of bytes written by print" .Vb 1 \& $num = $obj\->print_length; .Ve .Sp This returns the number of bytes successfully written by the most recent \f(CW\*(C`print()\*(C'\fR or \f(CW\*(C`put()\*(C'\fR. .IP "\fBprompt\fR \- pattern to match a prompt" 4 .IX Item "prompt - pattern to match a prompt" .Vb 1 \& $matchop = $obj\->prompt; \& \& $prev = $obj\->prompt($matchop); .Ve .Sp 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 \f(CW\*(C`login()\*(C'\fR and \f(CW\*(C`cmd()\*(C'\fR 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. .Sp With no argument this method returns the prompt set in the object. With an argument it sets the prompt to \fI\f(CI$matchop\fI\fR and returns the previous value. .Sp The default prompt is \f(CW\*(Aq/[\e$%#>] $/\*(Aq\fR .Sp Always use single quotes, instead of double quotes, to construct \&\fI\f(CI$matchop\fI\fR (e.g. \f(CW\*(Aq/bash\e$ $/\*(Aq\fR). If you're constructing a \s-1DOS\s0 like file path, you'll need to use four backslashes to represent one (e.g. \f(CW\*(Aq/c:\e\e\e\eusers\e\e\e\ebill>$/i\*(Aq\fR). .Sp Of course don't forget about regexp metacharacters like \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`[\*(C'\fR, or \&\f(CW\*(C`$\*(C'\fR. You'll only need a single backslash to quote them. The anchor metacharacters \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR refer to positions in the input buffer. .Sp The error mode action is performed when attempting to set this attribute with a match operator missing its opening delimiter. .IP "\fBput\fR \- write to object" 4 .IX Item "put - write to object" .Vb 1 \& $ok = $obj\->put($string); \& \& $ok = $obj\->put(String => $string, \& [Binmode => $mode,] \& [Errmode => $errmode,] \& [Telnetmode => $mode,] \& [Timeout => $secs,]); .Ve .Sp This method writes \fI\f(CI$string\fI\fR to the opened object and returns \f(CW1\fR if all data was successfully written. This method is like \f(CW\*(C`print()\*(C'\fR except that it doesn't write the trailing output_record_separator (\*(L"\en\*(R" by default). On time-out or other failures, the error mode action is performed. See \f(CW\*(C`errmode()\*(C'\fR. .Sp On failure, it's possible that some data was written. If you choose to try and recover from a put timing-out, use \f(CW\*(C`print_length()\*(C'\fR to determine how much was written before the error occurred. .Sp Optional named parameters are provided to override the current settings of binmode, errmode, telnetmode, and timeout. .IP "\fBrs\fR \- input line delimiter" 4 .IX Item "rs - input line delimiter" .Vb 1 \& $chars = $obj\->rs; \& \& $prev = $obj\->rs($chars); .Ve .Sp This method is synonymous with \f(CW\*(C`input_record_separator()\*(C'\fR. .IP "\fBsockfamily\fR \- \s-1IP\s0 address family of connected local socket" 4 .IX Item "sockfamily - IP address family of connected local socket" .Vb 1 \& $sockfamily = $obj\->sockfamily; .Ve .Sp This method returns which \s-1IP\s0 address family \f(CW\*(C`open()\*(C'\fR used to successfully connect. It is most useful when the requested address \&\f(CW\*(C`family()\*(C'\fR for \f(CW\*(C`open()\*(C'\fR was \f(CW"any"\fR. Values returned may be \&\f(CW"ipv4"\fR, \f(CW"ipv6"\fR, or \f(CW""\fR (when not connected). .IP "\fBsockhost\fR \- \s-1IP\s0 address of this end of the socket connection" 4 .IX Item "sockhost - IP address of this end of the socket connection" .Vb 1 \& $ipaddr = $obj\->sockhost; .Ve .Sp This method returns a string which is the IPv4 or IPv6 address the local socket is bound to. It returns \f(CW""\fR when not connected. .IP "\fBsockport\fR \- \s-1TCP\s0 port of this end of the socket connection" 4 .IX Item "sockport - TCP port of this end of the socket connection" .Vb 1 \& $port = $obj\->sockport; .Ve .Sp This method returns the port number which the local socket is bound to. It returns \f(CW""\fR when not connected. .IP "\fBtelnetmode\fR \- turn off/on telnet command interpretation" 4 .IX Item "telnetmode - turn off/on telnet command interpretation" .Vb 1 \& $mode = $obj\->telnetmode; \& \& $prev = $obj\->telnetmode($mode); .Ve .Sp This method controls whether or not \s-1TELNET\s0 commands in the data stream are recognized and handled. The \s-1TELNET\s0 protocol uses certain character sequences sent in the data stream to control the session. If the port you're connecting to isn't using the \s-1TELNET\s0 protocol, then you should turn this mode off. The default is \fIon\fR. .Sp If no argument is given, the current mode is returned. .Sp If \fI\f(CI$mode\fI\fR is \f(CW0\fR then telnet mode is off. If \fI\f(CI$mode\fI\fR is \f(CW1\fR then telnet mode is on. .IP "\fBtimed_out\fR \- time-out indicator" 4 .IX Item "timed_out - time-out indicator" .Vb 1 \& $boolean = $obj\->timed_out; \& \& $prev = $obj\->timed_out($boolean); .Ve .Sp 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 \f(CW\*(C`timed_out()\*(C'\fR after a time-out error, you'd have to change the default error mode to something other than \f(CW"die"\fR. See \&\f(CW\*(C`errmode()\*(C'\fR. .Sp With no argument this method returns \f(CW1\fR if the previous method timed-out. With an argument it sets the indicator. Normally, only internal methods set this indicator. .IP "\fBtimeout\fR \- I/O time-out interval" 4 .IX Item "timeout - I/O time-out interval" .Vb 1 \& $secs = $obj\->timeout; \& \& $prev = $obj\->timeout($secs); .Ve .Sp This method sets the timeout interval 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. .Sp A timeout may be expressed as a relative or absolute value. If \&\fI\f(CI$secs\fI\fR 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 \f(CW\*(C`time()\*(C'\fR may be used to obtain an absolute time value. For a relative time-out value less than $^T, time-out happens \fI\f(CI$secs\fI\fR from when the method begins. .Sp If \fI\f(CI$secs\fI\fR is \f(CW0\fR then time-out occurs if the data cannot be immediately read or written. Use the undefined value to turn off timing-out completely. .Sp With no argument this method returns the timeout set in the object. With an argument it sets the timeout to \fI\f(CI$secs\fI\fR and returns the previous value. The default timeout value is \f(CW10\fR seconds. .Sp A warning is printed to \s-1STDERR\s0 when attempting to set this attribute to something that is not an \f(CW\*(C`undef\*(C'\fR or a non-negative integer. .IP "\fBwaitfor\fR \- wait for pattern in the input" 4 .IX Item "waitfor - wait for pattern in the input" .Vb 7 \& $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,]); .Ve .Sp 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. .Sp In a list context the characters before the match and the matched characters are returned in \fI\f(CI$prematch\fI\fR and \fI\f(CI$match\fI\fR. In a scalar context, the matched characters and all characters before it are discarded and \f(CW1\fR is returned on success. On time-out, eof, or other failures, for both list and scalar context, the error mode action is performed. See \f(CW\*(C`errmode()\*(C'\fR. .Sp You can specify more than one pattern or string by simply providing multiple \fIMatch\fR and/or \fIString\fR named parameters. A \fI\f(CI$matchop\fI\fR must be a string representing a valid Perl pattern match operator. The \fI\f(CI$string\fI\fR is just a substring to find in the input stream. .Sp Use \f(CW\*(C`dump_log()\*(C'\fR to debug when this method keeps timing-out and you don't think it should. .Sp An optional named parameter is provided to override the current setting of timeout. .Sp To avoid unexpected backslash interpretation, always use single quotes instead of double quotes to construct a match operator argument for \&\f(CW\*(C`prompt()\*(C'\fR and \f(CW\*(C`waitfor()\*(C'\fR (e.g. \f(CW\*(Aq/bash\e$ $/\*(Aq\fR). If you're constructing a \s-1DOS\s0 like file path, you'll need to use four backslashes to represent one (e.g. \f(CW\*(Aq/c:\e\e\e\eusers\e\e\e\ebill>$/i\*(Aq\fR). .Sp Of course don't forget about regexp metacharacters like \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`[\*(C'\fR, or \&\f(CW\*(C`$\*(C'\fR. You'll only need a single backslash to quote them. The anchor metacharacters \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR refer to positions in the input buffer. .Sp Optional named parameters are provided to override the current settings of binmode, errmode, telnetmode, and timeout. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\s-1RFC 854\s0" 2 .IX Item "RFC 854" \&\s-1TELNET\s0\ Protocol\ Specification .Sp http://tools.ietf.org/html/rfc854 .IP "\s-1RFC 1143\s0" 2 .IX Item "RFC 1143" Q\ Method\ of\ Implementing\ \s-1TELNET\s0\ Option\ Negotiation .Sp http://tools.ietf.org/html/rfc1143 .IP "\s-1TELNET\s0 Option Assignments" 2 .IX Item "TELNET Option Assignments" http://www.iana.org/assignments/telnet\-options .SH "EXAMPLES" .IX Header "EXAMPLES" Setting \f(CW\*(C`prompt()\*(C'\fR to match a user's shell prompt can be tricky. This example logs in without knowing the shell prompt and then sets it to match \f(CW\*(C`prompt()\*(C'\fR. It requires /usr/bin/env and /bin/sh on the remote host. .PP .Vb 4 \& my $host = \*(Aqyour_destination_host_here\*(Aq; \& my $user = \*(Aqyour_username_here\*(Aq; \& my $passwd = \*(Aqyour_password_here\*(Aq; \& my ($t, @output); \& \& ## Create a Net::Telnet object. \& use Net::Telnet (); \& $t = new Net::Telnet (Timeout => 10); \& \& ## Connect and login. \& $t\->open($host); \& \& $t\->waitfor(\*(Aq/login: ?$/i\*(Aq); \& $t\->print($user); \& \& $t\->waitfor(\*(Aq/password: ?$/i\*(Aq); \& $t\->print($passwd); \& \& ## Switch to a known shell, using a known prompt. \& $t\->prompt(\*(Aq/ $/\*(Aq); \& $t\->errmode("return"); \& \& $t\->cmd("exec /usr/bin/env \*(AqPS1= \*(Aq /bin/sh \-i") \& or die "login failed to remote host $host"; \& \& $t\->errmode("die"); \& \& ## Now you can do cmd() to your heart\*(Aqs content. \& @output = $t\->cmd("uname \-a"); \& print @output; \& \& exit; .Ve .PP Usually you want the remote \s-1TERM\s0 environment variable to be set to something like \*(L"dumb\*(R" so you don't read escape sequences meant to be interpreted by a display terminal. It is best to set it via \f(CW\*(C`cmd()\*(C'\fR, or via \f(CW\*(C`waitfor()\*(C'\fR and \&\f(CW\*(C`print()\*(C'\fR. It is also possible to negotiate the terminal type via telnet. Here is how to do that. .PP .Vb 2 \& ## Module import. \& use Net::Telnet qw(TELNET_IAC TELNET_SB TELNET_SE TELOPT_TTYPE); \& \& ## Global variables. \& my $Term; \& \& ## Main program. \& { \& my $host = "your_destination_host_here"; \& my $user = "your_username_here"; \& my $passwd = "your_password_here"; \& my $prompt = \*(Aq/bash\e$ $/\*(Aq; # your regexp for shell prompt here \& my $t; \& \& $t = new Net::Telnet (Prompt => $prompt); \& \& ## Set up callbacks to negotiate terminal type. \& $t\->option_callback(sub {}); \& $t\->suboption_callback(\e&subopt_callback); \& $t\->option_accept(Do => TELOPT_TTYPE); \& \& ## Login and print value of TERM. \& $Term = "dumb"; \& $t\->open($host); \& $t\->login($user, $passwd); \& print $t\->cmd(\*(Aqhostname\*(Aq); \& print "TERM=", $t\->cmd(\*(Aqecho $TERM\*(Aq); \& $t\->close; \& \& exit; \& } # end main program \& \& sub subopt_callback { \& my ($t, $option, $parameters) = @_; \& my $telcmd; \& \& if ($option == TELOPT_TTYPE) { \& $telcmd = pack("C4 A* C2", TELNET_IAC, TELNET_SB, TELOPT_TTYPE, 0, \& $Term, TELNET_IAC, TELNET_SE); \& $t\->put(String => $telcmd, \& Telnetmode => 0); \& } \& \& 1; \& } # end sub subopt_callback .Ve .PP You can also use Net::Telnet to interact with local programs. This example changes a user's login password. It introduces the \f(CW\*(C`spawn()\*(C'\fR subroutine to start a program and associate a filehandle with its standard I/O. Because the passwd program always prompts for passwords on its controlling terminal, the IO::Pty module is used to create a new pseudo terminal for use by passwd. The Net::Telnet object reads and writes to that pseudo terminal. To use the code below, substitute \&\*(L"changeme\*(R" with the actual old and new passwords. .PP ## Main program. { my ($pty, \f(CW$passwd\fR); my \f(CW$oldpw\fR = \*(L"changeme\*(R"; my \f(CW$newpw\fR = \*(L"changeme\*(R"; .PP .Vb 2 \& ## Start passwd program. \& $pty = spawn("passwd"); \& \& ## Create a Net::Telnet object to perform I/O on passwd\*(Aqs tty. \& use Net::Telnet; \& $passwd = new Net::Telnet (\-fhopen => $pty, \& \-timeout => 2, \& \-output_record_separator => "\er", \& \-telnetmode => 0, \& \-cmd_remove_mode => 1); \& $passwd\->errmode("return"); \& \& ## Send existing password. \& $passwd\->waitfor(\*(Aq/password: ?$/i\*(Aq) \& or die "no old password prompt: ", $passwd\->lastline; \& $passwd\->print($oldpw); \& \& ## Send new password. \& $passwd\->waitfor(\*(Aq/new (\ew+\es)?password: ?$/i\*(Aq) \& or die "bad old password: ", $passwd\->lastline; \& $passwd\->print($newpw); \& \& ## Send new password verification. \& $passwd\->waitfor(\*(Aq/new (\ew+\es)?password: ?$/i\*(Aq) \& or die "bad new password: ", $passwd\->lastline; \& $passwd\->print($newpw); \& \& ## Display success or failure. \& $passwd\->waitfor(\*(Aq/(changed|updated)/\*(Aq) \& or die "bad new password: ", $passwd\->lastline; \& print $passwd\->lastline; \& \& $passwd\->close; \& exit; \&} # end main program .Ve .PP sub spawn { my (@cmd) = \f(CW@_\fR; my ($pid, \f(CW$pty\fR, \f(CW$tty\fR, \f(CW$tty_fd\fR); .PP .Vb 4 \& ## 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: $!\en" unless defined $pid; \& \& ## Disassociate process from its controlling terminal. \& use POSIX (); \& POSIX::setsid() \& or die "setsid failed: $!"; \& \& ## Associate process with a new controlling terminal. \& $pty\->make_slave_controlling_terminal; \& $tty = $pty\->slave; \& $tty_fd = $tty\->fileno; \& close $pty; \& \& ## Make standard I/O 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]\en"; \& } # end child process \& \& $pty; \&} # end sub spawn .Ve .PP Here is an example that uses the openssh program to connect to a remote host. It uses the \f(CW\*(C`spawn()\*(C'\fR subroutine, from the password changing example above, to start the ssh program and then read and write to it via a Net::Telnet object. This example turns off ssh host key checking, which reduces your ability to know when someone on the network is impersonating the remote host. To use the code below, substitute \*(L"changeme\*(R" with the actual host, user, password, and command prompt. .PP .Vb 7 \& ## Main program. \& { \& my $host = "changeme"; \& my $user = "changeme"; \& my $passwd = "changeme"; \& my $prompt = \*(Aq/changeme\e$ $/\*(Aq; \& my ($buf, $match, $pty, $ssh, @lines); \& \& ## Start ssh program. \& $pty = spawn("ssh", \& "\-l", $user, \& "\-e", "none", \& "\-F", "/dev/null", \& "\-o", "PreferredAuthentications=password", \& "\-o", "NumberOfPasswordPrompts=1", \& "\-o", "StrictHostKeyChecking=no", \& "\-o", "UserKnownHostsFile=/dev/null", \& $host); \& \& ## Create a Net::Telnet object to perform I/O on ssh\*(Aqs tty. \& use Net::Telnet; \& $ssh = new Net::Telnet (\-fhopen => $pty, \& \-prompt => $prompt, \& \-telnetmode => 0, \& \-output_record_separator => "\er", \& \-cmd_remove_mode => 1); \& \& ## Wait for the password prompt and send password. \& $ssh\->waitfor(\-match => \*(Aq/password: ?$/i\*(Aq, \& \-errmode => "return") \& or die "problem connecting to \e"$host\e": ", $ssh\->lastline; \& $ssh\->print($passwd); \& \& ## Wait for the shell prompt. \& (undef, $match) = $ssh\->waitfor(\-match => $ssh\->prompt, \& \-match => \*(Aq/^Permission denied/m\*(Aq, \& \-errmode => "return") \& or return $ssh\->error("login failed: expected shell prompt ", \& "doesn\*(Aqt match actual\en"); \& return $ssh\->error("login failed: bad login\-name or password\en") \& if $match =~ /^Permission denied/m; \& \& ## Run commands on remote host. \& print $ssh\->cmd("hostname"); \& print $ssh\->cmd("uptime"); \& \& $ssh\->close; \& exit; \& } # end main program .Ve .PP Some shells have a rather restrictive 255 character line limit. If you run into this problem, here is an example for sending lines longer than 254 as a sequence of shorter lines. .PP .Vb 10 \& ## Main program. \& { \& my $host = "changeme"; \& my $user = "changeme"; \& my $passwd = "changeme"; \& my $prompt = \*(Aq/changeme\e$ $/\*(Aq; \& my $cmd = join("", "echo ", \& "11111111112222222222333333333344444444445555555555", \& "66666666667777777777888888888899999999990000000000", \& "11111111112222222222333333333344444444445555555555", \& "66666666667777777777888888888899999999990000000000", \& "11111111112222222222333333333344444444445555555555", \& "66666666667777777777888888888899999999990000000000"); \& \& use Net::Telnet (); \& my $t = new Net::Telnet (\-prompt => $prompt); \& $t\->open($host); \& $t\->login($user, $passwd); \& \& my @output = cmd_unixlong($t, $cmd); \& print @output; \& \& exit; \& } # end main program \& \& sub cmd_unixlong { \& my ($obj, $cmd) = @_; \& my ($line, $pos); \& my $max_tty_line = 254; \& \& ## Start a Bourne shell. \& $obj\->cmd(\-string => "/usr/bin/env " . \& "\*(AqPS1= \*(Aq \*(AqPS2= \*(Aq /bin/sh \-i", \& \-prompt => \*(Aq/ $/\*(Aq) \& or return; \& \& ## Break\-up the one large command line and send as shorter lines. \& $pos = 0; \& while (1) { \& $line = substr $cmd, $pos, $max_tty_line; \& $pos += length $line; \& last unless $pos < length $cmd; \& \& ## Send the line with continuation char. \& $obj\->cmd(\-string => "$line\e\e", \& \-prompt => \*(Aq/ $/\*(Aq) \& or return; \& } \& \& ## Send the last line and return the output. \& $obj\->cmd("$line ; exit"); \& } # end sub cmd_unixlong .Ve .SH "AUTHOR" .IX Header "AUTHOR" Jay Rogers .SH "CREDITS" .IX Header "CREDITS" Dave Martin, Dave Cardosi .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 1997, 2000, 2002, 2013 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.