1Net::Telnet(3)        User Contributed Perl Documentation       Net::Telnet(3)
2
3
4

NAME

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

SYNOPSIS

9       "use Net::Telnet ();"
10
11       see METHODS section below
12

DESCRIPTION

14       Net::Telnet allows you to make client connections to a TCP port and do
15       network I/O, especially to a port using the TELNET protocol.  Simple
16       I/O methods such as print, get, and getline are provided.  More
17       sophisticated interactive features are provided because connecting to a
18       TELNET port ultimately means communicating with a program designed for
19       human interaction.  These interactive features include the ability to
20       specify a time-out and to wait for patterns to appear in the input
21       stream, such as the prompt from a shell.
22
23       Other reasons to use this module than strictly with a TELNET port are:
24
25       · You're not familiar with sockets and you want a simple way to make
26         client connections to TCP services.
27
28       · You want to be able to specify your own time-out while connecting,
29         reading, or writing.
30
31       · You're communicating with an interactive program at the other end of
32         some socket or pipe and you want to wait for certain patterns to
33         appear.
34
35       Here's an example that prints who's logged-on to the remote host
36       sparky.  In addition to a username and password, you must also know the
37       user's shell prompt, which for this example is "bash$"
38
39           use Net::Telnet ();
40           $t = new Net::Telnet (Timeout => 10,
41                                 Prompt => '/bash\$ $/');
42           $t->open("sparky");
43           $t->login($username, $passwd);
44           @lines = $t->cmd("who");
45           print @lines;
46
47       More examples are in the EXAMPLES section below.
48
49       Usage questions should be directed to the Usenet newsgroup
50       comp.lang.perl.modules.
51
52       Contact me, Jay Rogers <jay@rgrs.com>, if you find any bugs or have
53       suggestions for improvement.
54
55   What To Know Before Using
56       · All output is flushed while all input is buffered.  Each object
57         contains its own input buffer.
58
59       · The output record separator for "print()" and "cmd()" is set to "\n"
60         by default, so that you don't have to append all your commands with a
61         newline.  To avoid printing a trailing "\n" use "put()" or set the
62         output_record_separator to "".
63
64       · The methods "login()" and "cmd()" use the prompt setting in the
65         object to determine when a login or remote command is complete.
66         Those methods will fail with a time-out if you don't set the prompt
67         correctly.
68
69       · Use a combination of "print()" and "waitfor()" as an alternative to
70         "login()" or "cmd()" when they don't do what you want.
71
72       · Errors such as timing-out are handled according to the error mode
73         action.  The default action is to print an error message to standard
74         error and have the program die.  See the "errmode()" method for more
75         information.
76
77       · When constructing the match operator argument for "prompt()" or
78         "waitfor()", always use single quotes instead of double quotes to
79         avoid unexpected backslash interpretation (e.g. '/bash\$ $/').  If
80         you're constructing a DOS like file path, you'll need to use four
81         backslashes to represent one (e.g. '/c:\\\\users\\\\bill>$/i').
82
83         Of course don't forget about regexp metacharacters like ".", "[", or
84         "$".  You'll only need a single backslash to quote them.  The anchor
85         metacharacters "^" and "$" refer to positions in the input buffer.
86         To avoid matching characters read that look like a prompt, it's a
87         good idea to end your prompt pattern with the "$" anchor.  That way
88         the prompt will only match if it's the last thing read.
89
90       · In the input stream, each sequence of carriage return and line feed
91         (i.e. "\015\012" or CR LF) is converted to "\n".  In the output
92         stream, each occurrence of "\n" is converted to a sequence of CR LF.
93         See "binmode()" to change the behavior.  TCP protocols typically use
94         the ASCII sequence, carriage return and line feed to designate a
95         newline.
96
97       · Timing-out while making a connection is disabled for machines that
98         don't support the "alarm()" function.  Most notably these include MS-
99         Windows machines.
100
101       · You'll need to be running at least Perl version 5.002 to use this
102         module.  This module does not require any libraries that don't
103         already come with a standard Perl distribution.
104
105         If you have the IO:: libraries installed (they come standard with
106         perl5.004 and later) then IO::Socket::INET is used as a base class,
107         otherwise FileHandle is used.
108
109       · Contact me, Jay Rogers <jay@rgrs.com>, if you find any bugs or have
110         suggestions for improvement.
111
112   Debugging
113       The typical usage bug causes a time-out error because you've made
114       incorrect assumptions about what the remote side actually sends.  The
115       easiest way to reconcile what the remote side sends with your
116       expectations is to use "input_log()" or "dump_log()".
117
118       "dump_log()" allows you to see the data being sent from the remote side
119       before any translation is done, while "input_log()" shows you the
120       results after translation.  The translation includes converting end of
121       line characters, removing and responding to TELNET protocol commands in
122       the data stream.
123
124   Style of Named Parameters
125       Two different styles of named parameters are supported.  This document
126       only shows the IO:: style:
127
128           Net::Telnet->new(Timeout => 20);
129
130       however the dash-option style is also allowed:
131
132           Net::Telnet->new(-timeout => 20);
133
134   Connecting to a Remote MS-Windows Machine
135       By default MS-Windows doesn't come with a TELNET server.  However third
136       party TELNET servers are available.  Unfortunately many of these
137       servers falsely claim to be a TELNET server.  This is especially true
138       of the so-called "Microsoft Telnet Server" that comes installed with
139       some newer versions MS-Windows.
140
141       When a TELNET server first accepts a connection, it must use the ASCII
142       control characters carriage-return and line-feed to start a new line
143       (see RFC854).  A server like the "Microsoft Telnet Server" that doesn't
144       do this, isn't a TELNET server.  These servers send ANSI terminal
145       escape sequences to position to a column on a subsequent line and to
146       even position while writing characters that are adjacent to each other.
147       Worse, when sending output these servers resend previously sent command
148       output in a misguided attempt to display an entire terminal screen.
149
150       Connecting Net::Telnet to one of these false TELNET servers makes your
151       job of parsing command output very difficult.  It's better to replace a
152       false TELNET server with a real TELNET server.  The better TELNET
153       servers for MS-Windows allow you to avoid the ANSI escapes by turning
154       off something some of them call console mode.
155

METHODS

157       In the calling sequences below, square brackets [] represent optional
158       parameters.
159
160       new - create a new Net::Telnet object
161               $obj = new Net::Telnet ([$host]);
162
163               $obj = new Net::Telnet ([Binmode    => $mode,]
164                                       [Cmd_remove_mode => $mode,]
165                                       [Dump_Log   => $filename,]
166                                       [Errmode    => $errmode,]
167                                       [Fhopen     => $filehandle,]
168                                       [Host       => $host,]
169                                       [Input_log  => $file,]
170                                       [Input_record_separator => $chars,]
171                                       [Option_log => $file,]
172                                       [Ors        => $chars,]
173                                       [Output_log => $file,]
174                                       [Output_record_separator => $chars,]
175                                       [Port       => $port,]
176                                       [Prompt     => $matchop,]
177                                       [Rs         => $chars,]
178                                       [Telnetmode => $mode,]
179                                       [Timeout    => $secs,]);
180
181           This is the constructor for Net::Telnet objects.  A new object is
182           returned on success, the error mode action is performed on failure
183           - see "errmode()".  The optional arguments are short-cuts to
184           methods of the same name.
185
186           If the $host argument is given then the object is opened by
187           connecting to TCP $port on $host.  Also see "open()".  The new
188           object returned is given the following defaults in the absence of
189           corresponding named parameters:
190
191           ·   The default Host is "localhost"
192
193           ·   The default Port is 23
194
195           ·   The default Prompt is '/[\$%#>] $/'
196
197           ·   The default Timeout is 10
198
199           ·   The default Errmode is "die"
200
201           ·   The default Output_record_separator is "\n".  Note that Ors is
202               synonymous with Output_record_separator.
203
204           ·   The default Input_record_separator is "\n".  Note that Rs is
205               synonymous with Input_record_separator.
206
207           ·   The default Binmode is 0, which means do newline translation.
208
209           ·   The default Telnetmode is 1, which means respond to TELNET
210               commands in the data stream.
211
212           ·   The default Cmd_remove_mode is "auto"
213
214           ·   The defaults for Dump_log, Input_log, Option_log, and
215               Output_log are "", which means that logging is turned-off.
216
217       binmode - toggle newline translation
218               $mode = $obj->binmode;
219
220               $prev = $obj->binmode($mode);
221
222           This method controls whether or not sequences of carriage returns
223           and line feeds (CR LF or more specifically "\015\012") are
224           translated.  By default they are translated (i.e. binmode is 0).
225
226           If no argument is given, the current mode is returned.
227
228           If $mode is 1 then binmode is on and newline translation is not
229           done.
230
231           If $mode is 0 then binmode is off and newline translation is done.
232           In the input stream, each sequence of CR LF is converted to "\n"
233           and in the output stream, each occurrence of "\n" is converted to a
234           sequence of CR LF.
235
236           Note that input is always buffered.  Changing binmode doesn't
237           effect what's already been read into the buffer.  Output is not
238           buffered and changing binmode will have an immediate effect.
239
240       break - send TELNET break character
241               $ok = $obj->break;
242
243           This method sends the TELNET break character.  This character is
244           provided because it's a signal outside the ASCII character set
245           which is currently given local meaning within many systems.  It's
246           intended to indicate that the Break Key or the Attention Key was
247           hit.
248
249           This method returns 1 on success, or performs the error mode action
250           on failure.
251
252       buffer - scalar reference to object's input buffer
253               $ref = $obj->buffer;
254
255           This method returns a scalar reference to the input buffer for
256           $obj.  Data in the input buffer is data that has been read from the
257           remote side but has yet to be read by the user.  Modifications to
258           the input buffer are returned by a subsequent read.
259
260       buffer_empty - discard all data in object's input buffer
261               $obj->buffer_empty;
262
263           This method removes all data in the input buffer for $obj.
264
265       close - close object
266               $ok = $obj->close;
267
268           This method closes the socket, file, or pipe associated with the
269           object.  It always returns a value of 1.
270
271       cmd - issue command and retrieve output
272               $ok = $obj->cmd($string);
273               $ok = $obj->cmd(String   => $string,
274                               [Output  => $ref,]
275                               [Cmd_remove_mode => $mode,]
276                               [Errmode => $mode,]
277                               [Input_record_separator => $chars,]
278                               [Ors     => $chars,]
279                               [Output_record_separator => $chars,]
280                               [Prompt  => $match,]
281                               [Rs      => $chars,]
282                               [Timeout => $secs,]);
283
284               @output = $obj->cmd($string);
285               @output = $obj->cmd(String   => $string,
286                                   [Output  => $ref,]
287                                   [Cmd_remove_mode => $mode,]
288                                   [Errmode => $mode,]
289                                   [Input_record_separator => $chars,]
290                                   [Ors     => $chars,]
291                                   [Output_record_separator => $chars,]
292                                   [Prompt  => $match,]
293                                   [Rs      => $chars,]
294                                   [Timeout => $secs,]);
295
296           This method sends the command $string, and reads the characters
297           sent back by the command up until and including the matching
298           prompt.  It's assumed that the program to which you're sending is
299           some kind of command prompting interpreter such as a shell.
300
301           The command $string is automatically appended with the
302           output_record_separator, By default that's "\n".  This is similar
303           to someone typing a command and hitting the return key.  Set the
304           output_record_separator to change this behavior.
305
306           In a scalar context, the characters read from the remote side are
307           discarded and 1 is returned on success.  On time-out, eof, or other
308           failures, the error mode action is performed.  See "errmode()".
309
310           In a list context, just the output generated by the command is
311           returned, one line per element.  In other words, all the characters
312           in between the echoed back command string and the prompt are
313           returned.  If the command happens to return no output, a list
314           containing one element, the empty string is returned.  This is so
315           the list will indicate true in a boolean context.  On time-out,
316           eof, or other failures, the error mode action is performed.  See
317           "errmode()".
318
319           The characters that matched the prompt may be retrieved using
320           "last_prompt()".
321
322           Many command interpreters echo back the command sent.  In most
323           situations, this method removes the first line returned from the
324           remote side (i.e. the echoed back command).  See
325           "cmd_remove_mode()" for more control over this feature.
326
327           Use "dump_log()" to debug when this method keeps timing-out and you
328           don't think it should.
329
330           Consider using a combination of "print()" and "waitfor()" as an
331           alternative to this method when it doesn't do what you want, e.g.
332           the command you send prompts for input.
333
334           The Output named parameter provides an alternative method of
335           receiving command output.  If you pass a scalar reference, all the
336           output (even if it contains multiple lines) is returned in the
337           referenced scalar.  If you pass an array or hash reference, the
338           lines of output are returned in the referenced array or hash.  You
339           can use "input_record_separator()" to change the notion of what
340           separates a line.
341
342           Optional named parameters are provided to override the current
343           settings of cmd_remove_mode, errmode, input_record_separator, ors,
344           output_record_separator, prompt, rs, and timeout.  Rs is synonymous
345           with input_record_separator and ors is synonymous with
346           output_record_separator.
347
348       cmd_remove_mode - toggle removal of echoed commands
349               $mode = $obj->cmd_remove_mode;
350
351               $prev = $obj->cmd_remove_mode($mode);
352
353           This method controls how to deal with echoed back commands in the
354           output returned by cmd().  Typically, when you send a command to
355           the remote side, the first line of output returned is the command
356           echoed back.  Use this mode to remove the first line of output
357           normally returned by cmd().
358
359           If no argument is given, the current mode is returned.
360
361           If $mode is 0 then the command output returned from cmd() has no
362           lines removed.  If $mode is a positive integer, then the first
363           $mode lines of command output are stripped.
364
365           By default, $mode is set to "auto".  Auto means that whether or not
366           the first line of command output is stripped, depends on whether or
367           not the remote side offered to echo.  By default, Net::Telnet
368           always accepts an offer to echo by the remote side.  You can change
369           the default to reject such an offer using "option_accept()".
370
371           A warning is printed to STDERR when attempting to set this
372           attribute to something that's not "auto" or a non-negative integer.
373
374       dump_log - log all I/O in dump format
375               $fh = $obj->dump_log;
376
377               $fh = $obj->dump_log($fh);
378
379               $fh = $obj->dump_log($filename);
380
381           This method starts or stops dump format logging of all the object's
382           input and output.  The dump format shows the blocks read and
383           written in a hexadecimal and printable character format.  This
384           method is useful when debugging, however you might want to first
385           try "input_log()" as it's more readable.
386
387           If no argument is given, the current log filehandle is returned.
388           An empty string indicates logging is off.
389
390           To stop logging, use an empty string as an argument.
391
392           If an open filehandle is given, it is used for logging and
393           returned.  Otherwise, the argument is assumed to be the name of a
394           file, the file is opened and a filehandle to it is returned.  If
395           the file can't be opened for writing, the error mode action is
396           performed.
397
398       eof - end of file indicator
399               $eof = $obj->eof;
400
401           This method returns 1 if end of file has been read, otherwise it
402           returns an empty string.  Because the input is buffered this isn't
403           the same thing as $obj has closed.  In other words $obj can be
404           closed but there still can be stuff in the buffer to be read.
405           Under this condition you can still read but you won't be able to
406           write.
407
408       errmode - define action to be performed on error
409               $mode = $obj->errmode;
410
411               $prev = $obj->errmode($mode);
412
413           This method gets or sets the action used when errors are
414           encountered using the object.  The first calling sequence returns
415           the current error mode.  The second calling sequence sets it to
416           $mode and returns the previous mode.  Valid values for $mode are
417           "die" (the default), "return", a coderef, or an arrayref.
418
419           When mode is "die" and an error is encountered using the object,
420           then an error message is printed to standard error and the program
421           dies.
422
423           When mode is "return" then the method generating the error places
424           an error message in the object and returns an undefined value in a
425           scalar context and an empty list in list context.  The error
426           message may be obtained using "errmsg()".
427
428           When mode is a coderef, then when an error is encountered coderef
429           is called with the error message as its first argument.  Using this
430           mode you may have your own subroutine handle errors.  If coderef
431           itself returns then the method generating the error returns
432           undefined or an empty list depending on context.
433
434           When mode is an arrayref, the first element of the array must be a
435           coderef.  Any elements that follow are the arguments to coderef.
436           When an error is encountered, the coderef is called with its
437           arguments.  Using this mode you may have your own subroutine handle
438           errors.  If the coderef itself returns then the method generating
439           the error returns undefined or an empty list depending on context.
440
441           A warning is printed to STDERR when attempting to set this
442           attribute to something that's not "die", "return", a coderef, or an
443           arrayref whose first element isn't a coderef.
444
445       errmsg - most recent error message
446               $msg = $obj->errmsg;
447
448               $prev = $obj->errmsg(@msgs);
449
450           The first calling sequence returns the error message associated
451           with the object.  The empty string is returned if no error has been
452           encountered yet.  The second calling sequence sets the error
453           message for the object to the concatenation of @msgs and returns
454           the previous error message.  Normally, error messages are set
455           internally by a method when an error is encountered.
456
457       error - perform the error mode action
458               $obj->error(@msgs);
459
460           This method concatenates @msgs into a string and places it in the
461           object as the error message.  Also see "errmsg()".  It then
462           performs the error mode action.  Also see "errmode()".
463
464           If the error mode doesn't cause the program to die, then an
465           undefined value or an empty list is returned depending on the
466           context.
467
468           This method is primarily used by this class or a sub-class to
469           perform the user requested action when an error is encountered.
470
471       fhopen - use already open filehandle for I/O
472               $ok = $obj->fhopen($fh);
473
474           This method associates the open filehandle $fh with $obj for
475           further I/O.  Filehandle $fh must already be opened.
476
477           Suppose you want to use the features of this module to do I/O to
478           something other than a TCP port, for example STDIN or a filehandle
479           opened to read from a process.  Instead of opening the object for
480           I/O to a TCP port by using "open()" or "new()", call this method
481           instead.
482
483           The value 1 is returned success, the error mode action is performed
484           on failure.
485
486       get - read block of data
487               $data = $obj->get([Binmode    => $mode,]
488                                 [Errmode    => $errmode,]
489                                 [Telnetmode => $mode,]
490                                 [Timeout    => $secs,]);
491
492           This method reads a block of data from the object and returns it
493           along with any buffered data.  If no buffered data is available to
494           return, it will wait for data to read using the timeout specified
495           in the object.  You can override that timeout using $secs.  Also
496           see "timeout()".  If buffered data is available to return, it also
497           checks for a block of data that can be immediately read.
498
499           On eof an undefined value is returned.  On time-out or other
500           failures, the error mode action is performed.  To distinguish
501           between eof or an error occurring when the error mode is not set to
502           "die", use "eof()".
503
504           Optional named parameters are provided to override the current
505           settings of binmode, errmode, telnetmode, and timeout.
506
507       getline - read next line
508               $line = $obj->getline([Binmode    => $mode,]
509                                     [Errmode    => $errmode,]
510                                     [Input_record_separator => $chars,]
511                                     [Rs         => $chars,]
512                                     [Telnetmode => $mode,]
513                                     [Timeout    => $secs,]);
514
515           This method reads and returns the next line of data from the
516           object.  You can use "input_record_separator()" to change the
517           notion of what separates a line.  The default is "\n".  If a line
518           isn't immediately available, this method blocks waiting for a line
519           or a time-out.
520
521           On eof an undefined value is returned.  On time-out or other
522           failures, the error mode action is performed.  To distinguish
523           between eof or an error occurring when the error mode is not set to
524           "die", use "eof()".
525
526           Optional named parameters are provided to override the current
527           settings of binmode, errmode, input_record_separator, rs,
528           telnetmode, and timeout.  Rs is synonymous with
529           input_record_separator.
530
531       getlines - read next lines
532               @lines = $obj->getlines([Binmode    => $mode,]
533                                       [Errmode    => $errmode,]
534                                       [Input_record_separator => $chars,]
535                                       [Rs         => $chars,]
536                                       [Telnetmode => $mode,]
537                                       [Timeout    => $secs,]
538                                       [All        => $boolean,]);
539
540           This method reads and returns all the lines of data from the object
541           until end of file is read.  You can use "input_record_separator()"
542           to change the notion of what separates a line.  The default is
543           "\n".  A time-out error occurs if all the lines can't be read
544           within the time-out interval.  See "timeout()".
545
546           The behavior of this method was changed in version 3.03.  Prior to
547           version 3.03 this method returned just the lines available from the
548           next read.  To get that old behavior, use the optional named
549           parameter All and set $boolean to "" or 0.
550
551           If only eof is read then an empty list is returned.  On time-out or
552           other failures, the error mode action is performed.  Use "eof()" to
553           distinguish between reading only eof or an error occurring when the
554           error mode is not set to "die".
555
556           Optional named parameters are provided to override the current
557           settings of binmode, errmode, input_record_separator, rs,
558           telnetmode, and timeout.  Rs is synonymous with
559           input_record_separator.
560
561       host - name of remote host
562               $host = $obj->host;
563
564               $prev = $obj->host($host);
565
566           This method designates the remote host for "open()".  With no
567           argument it returns the current host name set in the object.  With
568           an argument it sets the current host name to $host and returns the
569           previous host name.  You may indicate the remote host using either
570           a hostname or an IP address.
571
572           The default value is "localhost".  It may also be set by "open()"
573           or "new()".
574
575       input_log - log all input
576               $fh = $obj->input_log;
577
578               $fh = $obj->input_log($fh);
579
580               $fh = $obj->input_log($filename);
581
582           This method starts or stops logging of input.  This is useful when
583           debugging.  Also see "dump_log()".  Because most command
584           interpreters echo back commands received, it's likely all your
585           output will also be in this log.  Note that input logging occurs
586           after newline translation.  See "binmode()" for details on newline
587           translation.
588
589           If no argument is given, the log filehandle is returned.  An empty
590           string indicates logging is off.
591
592           To stop logging, use an empty string as an argument.
593
594           If an open filehandle is given, it is used for logging and
595           returned.  Otherwise, the argument is assumed to be the name of a
596           file, the file is opened for logging and a filehandle to it is
597           returned.  If the file can't be opened for writing, the error mode
598           action is performed.
599
600       input_record_separator - input line delimiter
601               $chars = $obj->input_record_separator;
602
603               $prev = $obj->input_record_separator($chars);
604
605           This method designates the line delimiter for input.  It's used
606           with "getline()", "getlines()", and "cmd()" to determine lines in
607           the input.
608
609           With no argument this method returns the current input record
610           separator set in the object.  With an argument it sets the input
611           record separator to $chars and returns the previous value.  Note
612           that $chars must have length.
613
614           A warning is printed to STDERR when attempting to set this
615           attribute to a string with no length.
616
617       last_prompt - last prompt read
618               $string = $obj->last_prompt;
619
620               $prev = $obj->last_prompt($string);
621
622           With no argument this method returns the last prompt read by cmd()
623           or login().  See "prompt()".  With an argument it sets the last
624           prompt read to $string and returns the previous value.  Normally,
625           only internal methods set the last prompt.
626
627       lastline - last line read
628               $line = $obj->lastline;
629
630               $prev = $obj->lastline($line);
631
632           This method retrieves the last line read from the object.  This may
633           be a useful error message when the remote side abnormally closes
634           the connection.  Typically the remote side will print an error
635           message before closing.
636
637           With no argument this method returns the last line read from the
638           object.  With an argument it sets the last line read to $line and
639           returns the previous value.  Normally, only internal methods set
640           the last line.
641
642       login - perform standard login
643               $ok = $obj->login($username, $password);
644
645               $ok = $obj->login(Name     => $username,
646                                 Password => $password,
647                                 [Errmode => $mode,]
648                                 [Prompt  => $match,]
649                                 [Timeout => $secs,]);
650
651           This method performs a standard login by waiting for a login prompt
652           and responding with $username, then waiting for the password prompt
653           and responding with $password, and then waiting for the command
654           interpreter prompt.  If any of those prompts sent by the remote
655           side don't match what's expected, this method will time-out, unless
656           timeout is turned off.
657
658           Login prompt must match either of these case insensitive patterns:
659
660               /login[: ]*$/i
661               /username[: ]*$/i
662
663           Password prompt must match this case insensitive pattern:
664
665               /password[: ]*$/i
666
667           The command interpreter prompt must match the current setting of
668           prompt.  See "prompt()".
669
670           Use "dump_log()" to debug when this method keeps timing-out and you
671           don't think it should.
672
673           Consider using a combination of "print()" and "waitfor()" as an
674           alternative to this method when it doesn't do what you want, e.g.
675           the remote host doesn't prompt for a username.
676
677           On success, 1 is returned.  On time out, eof, or other failures,
678           the error mode action is performed.  See "errmode()".
679
680           Optional named parameters are provided to override the current
681           settings of errmode, prompt, and timeout.
682
683       max_buffer_length - maximum size of input buffer
684               $len = $obj->max_buffer_length;
685
686               $prev = $obj->max_buffer_length($len);
687
688           This method designates the maximum size of the input buffer.  An
689           error is generated when a read causes the buffer to exceed this
690           limit.  The default value is 1,048,576 bytes (1MB).  The input
691           buffer can grow much larger than the block size when you
692           continuously read using "getline()" or "waitfor()" and the data
693           stream contains no newlines or matching waitfor patterns.
694
695           With no argument, this method returns the current maximum buffer
696           length set in the object.  With an argument it sets the maximum
697           buffer length to $len and returns the previous value.  Values of
698           $len smaller than 512 will be adjusted to 512.
699
700           A warning is printed to STDERR when attempting to set this
701           attribute to something that isn't a positive integer.
702
703       ofs - field separator for print
704               $chars = $obj->ofs
705
706               $prev = $obj->ofs($chars);
707
708           This method is synonymous with "output_field_separator()".
709
710       open - connect to port on remote host
711               $ok = $obj->open($host);
712
713               $ok = $obj->open([Host    => $host,]
714                                [Port    => $port,]
715                                [Errmode => $mode,]
716                                [Timeout => $secs,]);
717
718           This method opens a TCP connection to $port on $host.  If either
719           argument is missing then the current value of "host()" or "port()"
720           is used.  Optional named parameters are provided to override the
721           current setting of errmode and timeout.
722
723           On success 1 is returned.  On time-out or other connection
724           failures, the error mode action is performed.  See "errmode()".
725
726           Time-outs don't work for this method on machines that don't
727           implement SIGALRM - most notably MS-Windows machines.  For those
728           machines, an error is returned when the system reaches its own
729           time-out while trying to connect.
730
731           A side effect of this method is to reset the alarm interval
732           associated with SIGALRM.
733
734       option_accept - indicate willingness to accept a TELNET option
735               $fh = $obj->option_accept([Do   => $telopt,]
736                                         [Dont => $telopt,]
737                                         [Will => $telopt,]
738                                         [Wont => $telopt,]);
739
740           This method is used to indicate whether to accept or reject an
741           offer to enable a TELNET option made by the remote side.  If you're
742           using Do or Will to indicate a willingness to enable, then a
743           notification callback must have already been defined by a prior
744           call to "option_callback()".  See "option_callback()" for details
745           on receiving enable/disable notification of a TELNET option.
746
747           You can give multiple Do, Dont, Will, or Wont arguments for
748           different TELNET options in the same call to this method.
749
750           The following example describes the meaning of the named
751           parameters.  A TELNET option, such as "TELOPT_ECHO" used below, is
752           an integer constant that you can import from Net::Telnet.  See the
753           source in file Telnet.pm for the complete list.
754
755           ·   Do => "TELOPT_ECHO"
756
757               ·   we'll accept an offer to enable the echo option on the
758                   local side
759
760           ·   Dont => "TELOPT_ECHO"
761
762               ·   we'll reject an offer to enable the echo option on the
763                   local side
764
765           ·   Will => "TELOPT_ECHO"
766
767               ·   we'll accept an offer to enable the echo option on the
768                   remote side
769
770           ·   Wont => "TELOPT_ECHO"
771
772               ·   we'll reject an offer to enable the echo option on the
773                   remote side
774
775           Use "option_send()" to send a request to the remote side to enable
776           or disable a particular TELNET option.
777
778       option_callback - define the option negotiation callback
779               $coderef = $obj->option_callback;
780
781               $prev = $obj->option_callback($coderef);
782
783           This method defines the callback subroutine that's called when a
784           TELNET option is enabled or disabled.  Once defined, the
785           option_callback may not be undefined.  However, calling this method
786           with a different $coderef changes it.
787
788           A warning is printed to STDERR when attempting to set this
789           attribute to something that isn't a coderef.
790
791           Here are the circumstances that invoke $coderef:
792
793           ·   An option becomes enabled because the remote side requested an
794               enable and "option_accept()" had been used to arrange that it
795               be accepted.
796
797           ·   The remote side arbitrarily decides to disable an option that
798               is currently enabled.  Note that Net::Telnet always accepts a
799               request to disable from the remote side.
800
801           ·   "option_send()" was used to send a request to enable or disable
802               an option and the response from the remote side has just been
803               received.  Note, that if a request to enable is rejected then
804               $coderef is still invoked even though the option didn't change.
805
806           Here are the arguments passed to &$coderef:
807
808               &$coderef($obj, $option, $is_remote,
809                         $is_enabled, $was_enabled, $buf_position);
810
811           ·   1.  $obj is the Net::Telnet object
812
813           ·   2.  $option is the TELNET option.  Net::Telnet exports
814               constants for the various TELNET options which just equate to
815               an integer.
816
817           ·   3.  $is_remote is a boolean indicating for which side the
818               option applies.
819
820           ·   4.  $is_enabled is a boolean indicating the option is enabled
821               or disabled
822
823           ·   5.  $was_enabled is a boolean indicating the option was
824               previously enabled or disabled
825
826           ·   6.  $buf_position is an integer indicating the position in the
827               object's input buffer where the option takes effect.  See
828               "buffer()" to access the object's input buffer.
829
830       option_log - log all TELNET options sent or received
831               $fh = $obj->option_log;
832
833               $fh = $obj->option_log($fh);
834
835               $fh = $obj->option_log($filename);
836
837           This method starts or stops logging of all TELNET options being
838           sent or received.  This is useful for debugging when you send
839           options via "option_send()" or you arrange to accept option
840           requests from the remote side via "option_accept()".  Also see
841           "dump_log()".
842
843           If no argument is given, the log filehandle is returned.  An empty
844           string indicates logging is off.
845
846           To stop logging, use an empty string as an argument.
847
848           If an open filehandle is given, it is used for logging and
849           returned.  Otherwise, the argument is assumed to be the name of a
850           file, the file is opened for logging and a filehandle to it is
851           returned.  If the file can't be opened for writing, the error mode
852           action is performed.
853
854       option_send - send TELNET option negotiation request
855               $ok = $obj->option_send([Do    => $telopt,]
856                                       [Dont  => $telopt,]
857                                       [Will  => $telopt,]
858                                       [Wont  => $telopt,]
859                                       [Async => $boolean,]);
860
861           This method is not yet implemented.  Look for it in a future
862           version.
863
864       option_state - get current state of a TELNET option
865               $hashref = $obj->option_state($telopt);
866
867           This method returns a hashref containing a copy of the current
868           state of TELNET option $telopt.
869
870           Here are the values returned in the hash:
871
872           ·   $hashref->{remote_enabled}
873
874               ·   boolean that indicates if the option is enabled on the
875                   remote side.
876
877           ·   $hashref->{remote_enable_ok}
878
879               ·   boolean that indicates if it's ok to accept an offer to
880                   enable this option on the remote side.
881
882           ·   $hashref->{remote_state}
883
884               ·   string used to hold the internal state of option
885                   negotiation for this option on the remote side.
886
887           ·   $hashref->{local_enabled}
888
889               ·   boolean that indicates if the option is enabled on the
890                   local side.
891
892           ·   $hashref->{local_enable_ok}
893
894               ·   boolean that indicates if it's ok to accept an offer to
895                   enable this option on the local side.
896
897           ·   $hashref->{local_state}
898
899               ·   string used to hold the internal state of option
900                   negotiation for this option on the local side.
901
902       ors - output line delimiter
903               $chars = $obj->ors;
904
905               $prev = $obj->ors($chars);
906
907           This method is synonymous with "output_record_separator()".
908
909       output_field_separator - field separator for print
910               $chars = $obj->output_field_separator;
911
912               $prev = $obj->output_field_separator($chars);
913
914           This method designates the output field separator for "print()".
915           Ordinarily the print method simply prints out the comma separated
916           fields you specify.  Set this to specify what's printed between
917           fields.
918
919           With no argument this method returns the current output field
920           separator set in the object.  With an argument it sets the output
921           field separator to $chars and returns the previous value.
922
923           By default it's set to an empty string.
924
925       output_log - log all output
926               $fh = $obj->output_log;
927
928               $fh = $obj->output_log($fh);
929
930               $fh = $obj->output_log($filename);
931
932           This method starts or stops logging of output.  This is useful when
933           debugging.  Also see "dump_log()".  Because most command
934           interpreters echo back commands received, it's likely all your
935           output would also be in an input log.  See "input_log()".  Note
936           that output logging occurs before newline translation.  See
937           "binmode()" for details on newline translation.
938
939           If no argument is given, the log filehandle is returned.  An empty
940           string indicates logging is off.
941
942           To stop logging, use an empty string as an argument.
943
944           If an open filehandle is given, it is used for logging and
945           returned.  Otherwise, the argument is assumed to be the name of a
946           file, the file is opened for logging and a filehandle to it is
947           returned.  If the file can't be opened for writing, the error mode
948           action is performed.
949
950       output_record_separator - output line delimiter
951               $chars = $obj->output_record_separator;
952
953               $prev = $obj->output_record_separator($chars);
954
955           This method designates the output line delimiter for "print()" and
956           "cmd()".  Set this to specify what's printed at the end of
957           "print()" and "cmd()".
958
959           The output record separator is set to "\n" by default, so there's
960           no need to append all your commands with a newline.  To avoid
961           printing the output_record_separator use "put()" or set the
962           output_record_separator to an empty string.
963
964           With no argument this method returns the current output record
965           separator set in the object.  With an argument it sets the output
966           record separator to $chars and returns the previous value.
967
968       port - remote port
969               $port = $obj->port;
970
971               $prev = $obj->port($port);
972
973           This method designates the remote TCP port.  With no argument this
974           method returns the current port number.  With an argument it sets
975           the current port number to $port and returns the previous port.  If
976           $port is a TCP service name, then it's first converted to a port
977           number using the perl function "getservbyname()".
978
979           The default value is 23.  It may also be set by "open()" or
980           "new()".
981
982           A warning is printed to STDERR when attempting to set this
983           attribute to something that's not a positive integer or a valid TCP
984           service name.
985
986       print - write to object
987               $ok = $obj->print(@list);
988
989           This method writes @list followed by the output_record_separator to
990           the open object and returns 1 if all data was successfully written.
991           On time-out or other failures, the error mode action is performed.
992           See "errmode()".
993
994           By default, the "output_record_separator()" is set to "\n" so all
995           your commands automatically end with a newline.  In most cases your
996           output is being read by a command interpreter which won't accept a
997           command until newline is read.  This is similar to someone typing a
998           command and hitting the return key.  To avoid printing a trailing
999           "\n" use "put()" instead or set the output_record_separator to an
1000           empty string.
1001
1002           On failure, it's possible that some data was written.  If you
1003           choose to try and recover from a print timing-out, use
1004           "print_length()" to determine how much was written before the error
1005           occurred.
1006
1007           You may also use the output field separator to print a string
1008           between the list elements.  See "output_field_separator()".
1009
1010       print_length - number of bytes written by print
1011               $num = $obj->print_length;
1012
1013           This returns the number of bytes successfully written by the most
1014           recent "print()" or "put()".
1015
1016       prompt - pattern to match a prompt
1017               $matchop = $obj->prompt;
1018
1019               $prev = $obj->prompt($matchop);
1020
1021           This method sets the pattern used to find a prompt in the input
1022           stream.  It must be a string representing a valid perl pattern
1023           match operator.  The methods "login()" and "cmd()" try to read
1024           until matching the prompt.  They will fail with a time-out error if
1025           the pattern you've chosen doesn't match what the remote side sends.
1026
1027           With no argument this method returns the prompt set in the object.
1028           With an argument it sets the prompt to $matchop and returns the
1029           previous value.
1030
1031           The default prompt is '/[\$%#>] $/'
1032
1033           Always use single quotes, instead of double quotes, to construct
1034           $matchop (e.g. '/bash\$ $/').  If you're constructing a DOS like
1035           file path, you'll need to use four backslashes to represent one
1036           (e.g. '/c:\\\\users\\\\bill>$/i').
1037
1038           Of course don't forget about regexp metacharacters like ".", "[",
1039           or "$".  You'll only need a single backslash to quote them.  The
1040           anchor metacharacters "^" and "$" refer to positions in the input
1041           buffer.
1042
1043           A warning is printed to STDERR when attempting to set this
1044           attribute with a match operator missing its opening delimiter.
1045
1046       put - write to object
1047               $ok = $obj->put($string);
1048
1049               $ok = $obj->put(String      => $string,
1050                               [Binmode    => $mode,]
1051                               [Errmode    => $errmode,]
1052                               [Telnetmode => $mode,]
1053                               [Timeout    => $secs,]);
1054
1055           This method writes $string to the opened object and returns 1 if
1056           all data was successfully written.  This method is like "print()"
1057           except that it doesn't write the trailing output_record_separator
1058           ("\n" by default).  On time-out or other failures, the error mode
1059           action is performed.  See "errmode()".
1060
1061           On failure, it's possible that some data was written.  If you
1062           choose to try and recover from a put timing-out, use
1063           "print_length()" to determine how much was written before the error
1064           occurred.
1065
1066           Optional named parameters are provided to override the current
1067           settings of binmode, errmode, telnetmode, and timeout.
1068
1069       rs - input line delimiter
1070               $chars = $obj->rs;
1071
1072               $prev = $obj->rs($chars);
1073
1074           This method is synonymous with "input_record_separator()".
1075
1076       telnetmode - turn off/on telnet command interpretation
1077               $mode = $obj->telnetmode;
1078
1079               $prev = $obj->telnetmode($mode);
1080
1081           This method controls whether or not TELNET commands in the data
1082           stream are recognized and handled.  The TELNET protocol uses
1083           certain character sequences sent in the data stream to control the
1084           session.  If the port you're connecting to isn't using the TELNET
1085           protocol, then you should turn this mode off.  The default is on.
1086
1087           If no argument is given, the current mode is returned.
1088
1089           If $mode is 0 then telnet mode is off.  If $mode is 1 then telnet
1090           mode is on.
1091
1092       timed_out - time-out indicator
1093               $boolean = $obj->timed_out;
1094
1095               $prev = $obj->timed_out($boolean);
1096
1097           This method indicates if a previous read, write, or open method
1098           timed-out.  Remember that timing-out is itself an error.  To be
1099           able to invoke "timed_out()" after a time-out error, you'd have to
1100           change the default error mode to something other than "die".  See
1101           "errmode()".
1102
1103           With no argument this method returns 1 if the previous method
1104           timed-out.  With an argument it sets the indicator.  Normally, only
1105           internal methods set this indicator.
1106
1107       timeout - I/O time-out interval
1108               $secs = $obj->timeout;
1109
1110               $prev = $obj->timeout($secs);
1111
1112           This method sets the timeout interval that's used when performing
1113           I/O or connecting to a port.  When a method doesn't complete within
1114           the timeout interval then it's an error and the error mode action
1115           is performed.
1116
1117           A timeout may be expressed as a relative or absolute value.  If
1118           $secs is greater than or equal to the time the program started, as
1119           determined by $^T, then it's an absolute time value for when time-
1120           out occurs.  The perl function "time()" may be used to obtain an
1121           absolute time value.  For a relative time-out value less than $^T,
1122           time-out happens $secs from when the method begins.
1123
1124           If $secs is 0 then time-out occurs if the data cannot be
1125           immediately read or written.  Use the undefined value to turn off
1126           timing-out completely.
1127
1128           With no argument this method returns the timeout set in the object.
1129           With an argument it sets the timeout to $secs and returns the
1130           previous value.  The default timeout value is 10 seconds.
1131
1132           A warning is printed to STDERR when attempting to set this
1133           attribute to something that's not an "undef" or a non-negative
1134           integer.
1135
1136       waitfor - wait for pattern in the input
1137               $ok = $obj->waitfor($matchop);
1138               $ok = $obj->waitfor([Match      => $matchop,]
1139                                   [String     => $string,]
1140                                   [Binmode    => $mode,]
1141                                   [Errmode    => $errmode,]
1142                                   [Telnetmode => $mode,]
1143                                   [Timeout    => $secs,]);
1144
1145               ($prematch, $match) = $obj->waitfor($matchop);
1146               ($prematch, $match) = $obj->waitfor([Match      => $matchop,]
1147                                                   [String     => $string,]
1148                                                   [Binmode    => $mode,]
1149                                                   [Errmode    => $errmode,]
1150                                                   [Telnetmode => $mode,]
1151                                                   [Timeout    => $secs,]);
1152
1153           This method reads until a pattern match or string is found in the
1154           input stream.  All the characters before and including the match
1155           are removed from the input stream.
1156
1157           In a list context the characters before the match and the matched
1158           characters are returned in $prematch and $match.  In a scalar
1159           context, the matched characters and all characters before it are
1160           discarded and 1 is returned on success.  On time-out, eof, or other
1161           failures, for both list and scalar context, the error mode action
1162           is performed.  See "errmode()".
1163
1164           You can specify more than one pattern or string by simply providing
1165           multiple Match and/or String named parameters.  A $matchop must be
1166           a string representing a valid Perl pattern match operator.  The
1167           $string is just a substring to find in the input stream.
1168
1169           Use "dump_log()" to debug when this method keeps timing-out and you
1170           don't think it should.
1171
1172           An optional named parameter is provided to override the current
1173           setting of timeout.
1174
1175           To avoid unexpected backslash interpretation, always use single
1176           quotes instead of double quotes to construct a match operator
1177           argument for "prompt()" and "waitfor()" (e.g. '/bash\$ $/').  If
1178           you're constructing a DOS like file path, you'll need to use four
1179           backslashes to represent one (e.g. '/c:\\\\users\\\\bill>$/i').
1180
1181           Of course don't forget about regexp metacharacters like ".", "[",
1182           or "$".  You'll only need a single backslash to quote them.  The
1183           anchor metacharacters "^" and "$" refer to positions in the input
1184           buffer.
1185
1186           Optional named parameters are provided to override the current
1187           settings of binmode, errmode, telnetmode, and timeout.
1188

SEE ALSO

1190       RFC 854
1191         TELNET Protocol Specification
1192
1193         ftp://ftp.isi.edu/in-notes/rfc854.txt
1194
1195       RFC 1143
1196         Q Method of Implementing TELNET Option Negotiation
1197
1198         ftp://ftp.isi.edu/in-notes/rfc1143.txt
1199
1200       TELNET Option Assignments
1201         http://www.iana.org/assignments/telnet-options
1202

EXAMPLES

1204       This example gets the current weather forecast for Brainerd, Minnesota.
1205
1206           my ($forecast, $t);
1207
1208           use Net::Telnet ();
1209           $t = new Net::Telnet;
1210           $t->open("rainmaker.wunderground.com");
1211
1212           ## Wait for first prompt and "hit return".
1213           $t->waitfor('/continue:.*$/');
1214           $t->print("");
1215
1216           ## Wait for second prompt and respond with city code.
1217           $t->waitfor('/city code.*$/');
1218           $t->print("BRD");
1219
1220           ## Read and print the first page of forecast.
1221           ($forecast) = $t->waitfor('/[ \t]+press return to continue/i');
1222           print $forecast;
1223
1224           exit;
1225
1226       This example checks a POP server to see if you have mail.
1227
1228           my ($hostname, $line, $passwd, $pop, $username);
1229
1230           $hostname = "your_destination_host_here";
1231           $username = "your_username_here";
1232           $passwd = "your_password_here";
1233
1234           use Net::Telnet ();
1235           $pop = new Net::Telnet (Telnetmode => 0);
1236           $pop->open(Host => $hostname,
1237                      Port => 110);
1238
1239
1240           ## Read connection message.
1241           $line = $pop->getline;
1242           die $line unless $line =~ /^\+OK/;
1243
1244           ## Send user name.
1245           $pop->print("user $username");
1246           $line = $pop->getline;
1247           die $line unless $line =~ /^\+OK/;
1248
1249           ## Send password.
1250           $pop->print("pass $passwd");
1251           $line = $pop->getline;
1252           die $line unless $line =~ /^\+OK/;
1253
1254           ## Request status of messages.
1255           $pop->print("list");
1256           $line = $pop->getline;
1257           print $line;
1258
1259           exit;
1260
1261       Here's an example that uses the ssh program to connect to a remote
1262       host.  Because the ssh program reads and writes to its controlling
1263       terminal, the IO::Pty module is used to create a new pseudo terminal
1264       for use by ssh.  A new Net::Telnet object is then created to read and
1265       write to that pseudo terminal.  To use the code below, substitute
1266       "changeme" with the actual host, user, password, and command prompt.
1267
1268           ## Main program.
1269           {
1270               my ($pty, $ssh, @lines);
1271               my $host = "changeme";
1272               my $user = "changeme";
1273               my $password = "changeme";
1274               my $prompt = '/changeme:~> $/';
1275
1276               ## Start ssh program.
1277               $pty = &spawn("ssh", "-l", $user, $host);  # spawn() defined below
1278
1279               ## Create a Net::Telnet object to perform I/O on ssh's tty.
1280               use Net::Telnet;
1281               $ssh = new Net::Telnet (-fhopen => $pty,
1282                                       -prompt => $prompt,
1283                                       -telnetmode => 0,
1284                                       -cmd_remove_mode => 1,
1285                                       -output_record_separator => "\r");
1286
1287               ## Login to remote host.
1288               $ssh->waitfor(-match => '/password: ?$/i',
1289                             -errmode => "return")
1290                   or die "problem connecting to host: ", $ssh->lastline;
1291               $ssh->print($password);
1292               $ssh->waitfor(-match => $ssh->prompt,
1293                             -errmode => "return")
1294                   or die "login failed: ", $ssh->lastline;
1295
1296               ## Send command, get and print its output.
1297               @lines = $ssh->cmd("who");
1298               print @lines;
1299
1300               exit;
1301           } # end main program
1302
1303           sub spawn {
1304               my(@cmd) = @_;
1305               my($pid, $pty, $tty, $tty_fd);
1306
1307               ## Create a new pseudo terminal.
1308               use IO::Pty ();
1309               $pty = new IO::Pty
1310                   or die $!;
1311
1312               ## Execute the program in another process.
1313               unless ($pid = fork) {  # child process
1314                   die "problem spawning program: $!\n" unless defined $pid;
1315
1316                   ## Disassociate process from existing controlling terminal.
1317                   use POSIX ();
1318                   POSIX::setsid
1319                       or die "setsid failed: $!";
1320
1321                   ## Associate process with a new controlling terminal.
1322                   $tty = $pty->slave;
1323                   $tty_fd = $tty->fileno;
1324                   close $pty;
1325
1326                   ## Make stdio use the new controlling terminal.
1327                   open STDIN, "<&$tty_fd" or die $!;
1328                   open STDOUT, ">&$tty_fd" or die $!;
1329                   open STDERR, ">&STDOUT" or die $!;
1330                   close $tty;
1331
1332                   ## Execute requested program.
1333                   exec @cmd
1334                       or die "problem executing $cmd[0]\n";
1335               } # end child process
1336
1337               $pty;
1338           } # end sub spawn
1339
1340       Here's an example that changes a user's login password.  Because the
1341       passwd program always prompts for passwords on its controlling
1342       terminal, the IO::Pty module is used to create a new pseudo terminal
1343       for use by passwd.  A new Net::Telnet object is then created to read
1344       and write to that pseudo terminal.  To use the code below, substitute
1345       "changeme" with the actual old and new passwords.
1346
1347           my ($pty, $passwd);
1348           my $oldpw = "changeme";
1349           my $newpw = "changeme";
1350
1351           ## Start passwd program.
1352           $pty = &spawn("passwd");  # spawn() defined above
1353
1354           ## Create a Net::Telnet object to perform I/O on passwd's tty.
1355           use Net::Telnet;
1356           $passwd = new Net::Telnet (-fhopen => $pty,
1357                                      -timeout => 2,
1358                                      -output_record_separator => "\r",
1359                                      -telnetmode => 0,
1360                                      -cmd_remove_mode => 1);
1361           $passwd->errmode("return");
1362
1363           ## Send existing password.
1364           $passwd->waitfor('/password: ?$/i')
1365               or die "no old password prompt: ", $passwd->lastline;
1366           $passwd->print($oldpw);
1367
1368           ## Send new password.
1369           $passwd->waitfor('/new password: ?$/i')
1370               or die "bad old password: ", $passwd->lastline;
1371           $passwd->print($newpw);
1372
1373           ## Send new password verification.
1374           $passwd->waitfor('/new password: ?$/i')
1375               or die "bad new password: ", $passwd->lastline;
1376           $passwd->print($newpw);
1377
1378           ## Display success or failure.
1379           $passwd->waitfor('/changed/')
1380               or die "bad new password: ", $passwd->lastline;
1381           print $passwd->lastline;
1382
1383           $passwd->close;
1384           exit;
1385
1386       Here's an example you can use to down load a file of any type.  The
1387       file is read from the remote host's standard output using cat.  To
1388       prevent any output processing, the remote host's standard output is put
1389       in raw mode using the Bourne shell.  The Bourne shell is used because
1390       some shells, notably tcsh, prevent changing tty modes.  Upon
1391       completion, FTP style statistics are printed to stderr.
1392
1393           my ($block, $filename, $host, $hostname, $k_per_sec, $line,
1394               $num_read, $passwd, $prevblock, $prompt, $size, $size_bsd,
1395               $size_sysv, $start_time, $total_time, $username);
1396
1397           $hostname = "your_destination_host_here";
1398           $username = "your_username_here";
1399           $passwd = "your_password_here";
1400           $filename = "your_download_file_here";
1401
1402           ## Connect and login.
1403           use Net::Telnet ();
1404           $host = new Net::Telnet (Timeout => 30,
1405                                    Prompt => '/[%#>] $/');
1406           $host->open($hostname);
1407           $host->login($username, $passwd);
1408
1409           ## Make sure prompt won't match anything in send data.
1410           $prompt = "_funkyPrompt_";
1411           $host->prompt("/$prompt\$/");
1412           $host->cmd("set prompt = '$prompt'");
1413
1414           ## Get size of file.
1415           ($line) = $host->cmd("/bin/ls -l $filename");
1416           ($size_bsd, $size_sysv) = (split ' ', $line)[3,4];
1417           if ($size_sysv =~ /^\d+$/) {
1418               $size = $size_sysv;
1419           }
1420           elsif ($size_bsd =~ /^\d+$/) {
1421               $size = $size_bsd;
1422           }
1423           else {
1424               die "$filename: no such file on $hostname";
1425           }
1426
1427           ## Start sending the file.
1428           binmode STDOUT;
1429           $host->binmode(1);
1430           $host->print("/bin/sh -c 'stty raw; cat $filename'");
1431           $host->getline;    # discard echoed back line
1432
1433           ## Read file a block at a time.
1434           $num_read = 0;
1435           $prevblock = "";
1436           $start_time = time;
1437           while (($block = $host->get) and ($block !~ /$prompt$/o)) {
1438               if (length $block >= length $prompt) {
1439                   print $prevblock;
1440                   $num_read += length $prevblock;
1441                   $prevblock = $block;
1442               }
1443               else {
1444                   $prevblock .= $block;
1445               }
1446
1447           }
1448           $host->close;
1449
1450           ## Print last block without trailing prompt.
1451           $prevblock .= $block;
1452           $prevblock =~ s/$prompt$//;
1453           print $prevblock;
1454           $num_read += length $prevblock;
1455           die "error: expected size $size, received size $num_read\n"
1456               unless $num_read == $size;
1457
1458           ## Print totals.
1459           $total_time = (time - $start_time) || 1;
1460           $k_per_sec = ($size / 1024) / $total_time;
1461           $k_per_sec = sprintf "%3.1f", $k_per_sec;
1462           warn("$num_read bytes received in $total_time seconds ",
1463                "($k_per_sec Kbytes/s)\n");
1464
1465           exit;
1466

AUTHOR

1468       Jay Rogers <jay@rgrs.com>
1469
1471       Copyright 1997, 2000, 2002 by Jay Rogers.  All rights reserved.  This
1472       program is free software; you can redistribute it and/or modify it
1473       under the same terms as Perl itself.
1474
1475
1476
1477perl v5.10.1                      2002-07-17                    Net::Telnet(3)
Impressum