Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "Net::Telnet 3" | |
132 | .TH Net::Telnet 3 "2002-07-16" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | Net::Telnet \- interact with TELNET port or other TCP ports | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | \&\f(CW\*(C`use Net::Telnet ();\*(C'\fR | |
138 | .PP | |
139 | see \s-1METHODS\s0 section below | |
140 | .SH "DESCRIPTION" | |
141 | .IX Header "DESCRIPTION" | |
142 | Net::Telnet allows you to make client connections to a \s-1TCP\s0 port and do | |
143 | network I/O, especially to a port using the \s-1TELNET\s0 protocol. Simple | |
144 | I/O methods such as print, get, and getline are provided. More | |
145 | sophisticated interactive features are provided because connecting to | |
146 | a \s-1TELNET\s0 port ultimately means communicating with a program designed | |
147 | for human interaction. These interactive features include the ability | |
148 | to specify a time-out and to wait for patterns to appear in the input | |
149 | stream, such as the prompt from a shell. | |
150 | .PP | |
151 | Other reasons to use this module than strictly with a \s-1TELNET\s0 port are: | |
152 | .IP "\(bu" 2 | |
153 | You're not familiar with sockets and you want a simple way to make | |
154 | client connections to \s-1TCP\s0 services. | |
155 | .IP "\(bu" 2 | |
156 | You want to be able to specify your own time-out while connecting, | |
157 | reading, or writing. | |
158 | .IP "\(bu" 2 | |
159 | You're communicating with an interactive program at the other end of | |
160 | some socket or pipe and you want to wait for certain patterns to | |
161 | appear. | |
162 | .PP | |
163 | Here's an example that prints who's logged-on to the remote host | |
164 | sparky. In addition to a username and password, you must also know | |
165 | the user's shell prompt, which for this example is \f(CW\*(C`bash$\*(C'\fR | |
166 | .PP | |
167 | .Vb 7 | |
168 | \& use Net::Telnet (); | |
169 | \& $t = new Net::Telnet (Timeout => 10, | |
170 | \& Prompt => '/bash\e$ $/'); | |
171 | \& $t->open("sparky"); | |
172 | \& $t->login($username, $passwd); | |
173 | \& @lines = $t->cmd("who"); | |
174 | \& print @lines; | |
175 | .Ve | |
176 | .PP | |
177 | More examples are in the \fB\s-1EXAMPLES\s0\fR section below. | |
178 | .PP | |
179 | Usage questions should be directed to the Usenet newsgroup | |
180 | comp.lang.perl.modules. | |
181 | .PP | |
182 | Contact me, Jay Rogers <jay@rgrs.com>, if you find any bugs or have | |
183 | suggestions for improvement. | |
184 | .Sh "What To Know Before Using" | |
185 | .IX Subsection "What To Know Before Using" | |
186 | .IP "\(bu" 2 | |
187 | All output is flushed while all input is buffered. Each object | |
188 | contains its own input buffer. | |
189 | .IP "\(bu" 2 | |
190 | The output record separator for \f(CW\*(C`print()\*(C'\fR and \f(CW\*(C`cmd()\*(C'\fR is set to | |
191 | \&\f(CW"\en"\fR by default, so that you don't have to append all your commands | |
192 | with a newline. To avoid printing a trailing \f(CW"\en"\fR use \f(CW\*(C`put()\*(C'\fR or | |
193 | set the \fIoutput_record_separator\fR to \f(CW""\fR. | |
194 | .IP "\(bu" 2 | |
195 | The methods \f(CW\*(C`login()\*(C'\fR and \f(CW\*(C`cmd()\*(C'\fR use the \fIprompt\fR setting in the | |
196 | object to determine when a login or remote command is complete. Those | |
197 | methods will fail with a time-out if you don't set the prompt | |
198 | correctly. | |
199 | .IP "\(bu" 2 | |
200 | Use a combination of \f(CW\*(C`print()\*(C'\fR and \f(CW\*(C`waitfor()\*(C'\fR as an alternative to | |
201 | \&\f(CW\*(C`login()\*(C'\fR or \f(CW\*(C`cmd()\*(C'\fR when they don't do what you want. | |
202 | .IP "\(bu" 2 | |
203 | Errors such as timing-out are handled according to the error mode | |
204 | action. The default action is to print an error message to standard | |
205 | error and have the program die. See the \f(CW\*(C`errmode()\*(C'\fR method for more | |
206 | information. | |
207 | .IP "\(bu" 2 | |
208 | When constructing the match operator argument for \f(CW\*(C`prompt()\*(C'\fR or | |
209 | \&\f(CW\*(C`waitfor()\*(C'\fR, always use single quotes instead of double quotes to | |
210 | avoid unexpected backslash interpretation (e.g. \f(CW'/bash\e$ $/'\fR). If | |
211 | you're constructing a \s-1DOS\s0 like file path, you'll need to use four | |
212 | backslashes to represent one (e.g. \f(CW'/c:\e\e\e\eusers\e\e\e\ebill>$/i'\fR). | |
213 | .Sp | |
214 | Of course don't forget about regexp metacharacters like \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`[\*(C'\fR, or | |
215 | \&\f(CW\*(C`$\*(C'\fR. You'll only need a single backslash to quote them. The anchor | |
216 | metacharacters \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR refer to positions in the input buffer. | |
217 | To avoid matching characters read that look like a prompt, it's a good | |
218 | idea to end your prompt pattern with the \f(CW\*(C`$\*(C'\fR anchor. That way the | |
219 | prompt will only match if it's the last thing read. | |
220 | .IP "\(bu" 2 | |
221 | In the input stream, each sequence of \fIcarriage return\fR and \fIline | |
222 | feed\fR (i.e. \f(CW"\e015\e012"\fR or \s-1CR\s0 \s-1LF\s0) is converted to \f(CW"\en"\fR. In the | |
223 | output stream, each occurrence of \f(CW"\en"\fR is converted to a sequence | |
224 | of \s-1CR\s0 \s-1LF\s0. See \f(CW\*(C`binmode()\*(C'\fR to change the behavior. \s-1TCP\s0 protocols | |
225 | typically use the \s-1ASCII\s0 sequence, carriage return and line feed to | |
226 | designate a newline. | |
227 | .IP "\(bu" 2 | |
228 | Timing-out while making a connection is disabled for machines that | |
229 | don't support the \f(CW\*(C`alarm()\*(C'\fR function. Most notably these include | |
230 | MS-Windows machines. | |
231 | .IP "\(bu" 2 | |
232 | You'll need to be running at least Perl version 5.002 to use this | |
233 | module. This module does not require any libraries that don't already | |
234 | come with a standard Perl distribution. | |
235 | .Sp | |
236 | If you have the \s-1IO::\s0 libraries installed (they come standard with | |
237 | perl5.004 and later) then IO::Socket::INET is used as a base class, | |
238 | otherwise FileHandle is used. | |
239 | .IP "\(bu" 2 | |
240 | Contact me, Jay Rogers <jay@rgrs.com>, if you find any bugs or have | |
241 | suggestions for improvement. | |
242 | .Sh "Debugging" | |
243 | .IX Subsection "Debugging" | |
244 | The typical usage bug causes a time-out error because you've made | |
245 | incorrect assumptions about what the remote side actually sends. The | |
246 | easiest way to reconcile what the remote side sends with your | |
247 | expectations is to use \f(CW\*(C`input_log()\*(C'\fR or \f(CW\*(C`dump_log()\*(C'\fR. | |
248 | .PP | |
249 | \&\f(CW\*(C`dump_log()\*(C'\fR allows you to see the data being sent from the remote | |
250 | side before any translation is done, while \f(CW\*(C`input_log()\*(C'\fR shows you | |
251 | the results after translation. The translation includes converting | |
252 | end of line characters, removing and responding to \s-1TELNET\s0 protocol | |
253 | commands in the data stream. | |
254 | .Sh "Style of Named Parameters" | |
255 | .IX Subsection "Style of Named Parameters" | |
256 | Two different styles of named parameters are supported. This document | |
257 | only shows the \s-1IO::\s0 style: | |
258 | .PP | |
259 | .Vb 1 | |
260 | \& Net::Telnet->new(Timeout => 20); | |
261 | .Ve | |
262 | .PP | |
263 | however the dash-option style is also allowed: | |
264 | .PP | |
265 | .Vb 1 | |
266 | \& Net::Telnet->new(-timeout => 20); | |
267 | .Ve | |
268 | .Sh "Connecting to a Remote MS-Windows Machine" | |
269 | .IX Subsection "Connecting to a Remote MS-Windows Machine" | |
270 | By default MS-Windows doesn't come with a \s-1TELNET\s0 server. However | |
271 | third party \s-1TELNET\s0 servers are available. Unfortunately many of these | |
272 | servers falsely claim to be a \s-1TELNET\s0 server. This is especially true | |
273 | of the so-called \*(L"Microsoft Telnet Server\*(R" that comes installed with | |
274 | some newer versions MS\-Windows. | |
275 | .PP | |
276 | When a \s-1TELNET\s0 server first accepts a connection, it must use the \s-1ASCII\s0 | |
277 | control characters carriage-return and line-feed to start a new line | |
278 | (see \s-1RFC854\s0). A server like the \*(L"Microsoft Telnet Server\*(R" that | |
279 | doesn't do this, isn't a \s-1TELNET\s0 server. These servers send \s-1ANSI\s0 | |
280 | terminal escape sequences to position to a column on a subsequent line | |
281 | and to even position while writing characters that are adjacent to | |
282 | each other. Worse, when sending output these servers resend | |
283 | previously sent command output in a misguided attempt to display an | |
284 | entire terminal screen. | |
285 | .PP | |
286 | Connecting Net::Telnet to one of these false \s-1TELNET\s0 servers makes your | |
287 | job of parsing command output very difficult. It's better to replace | |
288 | a false \s-1TELNET\s0 server with a real \s-1TELNET\s0 server. The better \s-1TELNET\s0 | |
289 | servers for MS-Windows allow you to avoid the \s-1ANSI\s0 escapes by turning | |
290 | off something some of them call \fIconsole mode\fR. | |
291 | .SH "METHODS" | |
292 | .IX Header "METHODS" | |
293 | In the calling sequences below, square brackets \fB[]\fR represent | |
294 | optional parameters. | |
295 | .IP "\fBnew\fR \- create a new Net::Telnet object" 4 | |
296 | .IX Item "new - create a new Net::Telnet object" | |
297 | .Vb 1 | |
298 | \& $obj = new Net::Telnet ([$host]); | |
299 | .Ve | |
300 | .Sp | |
301 | .Vb 17 | |
302 | \& $obj = new Net::Telnet ([Binmode => $mode,] | |
303 | \& [Cmd_remove_mode => $mode,] | |
304 | \& [Dump_Log => $filename,] | |
305 | \& [Errmode => $errmode,] | |
306 | \& [Fhopen => $filehandle,] | |
307 | \& [Host => $host,] | |
308 | \& [Input_log => $file,] | |
309 | \& [Input_record_separator => $chars,] | |
310 | \& [Option_log => $file,] | |
311 | \& [Ors => $chars,] | |
312 | \& [Output_log => $file,] | |
313 | \& [Output_record_separator => $chars,] | |
314 | \& [Port => $port,] | |
315 | \& [Prompt => $matchop,] | |
316 | \& [Rs => $chars,] | |
317 | \& [Telnetmode => $mode,] | |
318 | \& [Timeout => $secs,]); | |
319 | .Ve | |
320 | .Sp | |
321 | This is the constructor for Net::Telnet objects. A new object is | |
322 | returned on success, the error mode action is performed on failure \- | |
323 | see \f(CW\*(C`errmode()\*(C'\fR. The optional arguments are short-cuts to methods of | |
324 | the same name. | |
325 | .Sp | |
326 | If the \fI$host\fR argument is given then the object is opened by | |
327 | connecting to \s-1TCP\s0 \fI$port\fR on \fI$host\fR. Also see \f(CW\*(C`open()\*(C'\fR. The new | |
328 | object returned is given the following defaults in the absence of | |
329 | corresponding named parameters: | |
330 | .RS 4 | |
331 | .IP "\(bu" 4 | |
332 | The default \fIHost\fR is \f(CW"localhost"\fR | |
333 | .IP "\(bu" 4 | |
334 | The default \fIPort\fR is \f(CW23\fR | |
335 | .IP "\(bu" 4 | |
336 | The default \fIPrompt\fR is \f(CW'/[\e$%#>] $/'\fR | |
337 | .IP "\(bu" 4 | |
338 | The default \fITimeout\fR is \f(CW10\fR | |
339 | .IP "\(bu" 4 | |
340 | The default \fIErrmode\fR is \f(CW"die"\fR | |
341 | .IP "\(bu" 4 | |
342 | The default \fIOutput_record_separator\fR is \f(CW"\en"\fR. Note that \fIOrs\fR | |
343 | is synonymous with \fIOutput_record_separator\fR. | |
344 | .IP "\(bu" 4 | |
345 | The default \fIInput_record_separator\fR is \f(CW"\en"\fR. Note that \fIRs\fR is | |
346 | synonymous with \fIInput_record_separator\fR. | |
347 | .IP "\(bu" 4 | |
348 | The default \fIBinmode\fR is \f(CW0\fR, which means do newline translation. | |
349 | .IP "\(bu" 4 | |
350 | The default \fITelnetmode\fR is \f(CW1\fR, which means respond to \s-1TELNET\s0 | |
351 | commands in the data stream. | |
352 | .IP "\(bu" 4 | |
353 | The default \fICmd_remove_mode\fR is \f(CW"auto"\fR | |
354 | .IP "\(bu" 4 | |
355 | The defaults for \fIDump_log\fR, \fIInput_log\fR, \fIOption_log\fR, and | |
356 | \&\fIOutput_log\fR are \f(CW""\fR, which means that logging is turned\-off. | |
357 | .RE | |
358 | .RS 4 | |
359 | .RE | |
360 | .IP "\fBbinmode\fR \- toggle newline translation" 4 | |
361 | .IX Item "binmode - toggle newline translation" | |
362 | .Vb 1 | |
363 | \& $mode = $obj->binmode; | |
364 | .Ve | |
365 | .Sp | |
366 | .Vb 1 | |
367 | \& $prev = $obj->binmode($mode); | |
368 | .Ve | |
369 | .Sp | |
370 | This method controls whether or not sequences of carriage returns and | |
371 | line feeds (\s-1CR\s0 \s-1LF\s0 or more specifically \f(CW"\e015\e012"\fR) are translated. | |
372 | By default they are translated (i.e. binmode is \f(CW0\fR). | |
373 | .Sp | |
374 | If no argument is given, the current mode is returned. | |
375 | .Sp | |
376 | If \fI$mode\fR is \f(CW1\fR then binmode is \fIon\fR and newline translation is | |
377 | not done. | |
378 | .Sp | |
379 | If \fI$mode\fR is \f(CW0\fR then binmode is \fIoff\fR and newline translation is | |
380 | done. In the input stream, each sequence of \s-1CR\s0 \s-1LF\s0 is converted to | |
381 | \&\f(CW"\en"\fR and in the output stream, each occurrence of \f(CW"\en"\fR is | |
382 | converted to a sequence of \s-1CR\s0 \s-1LF\s0. | |
383 | .Sp | |
384 | Note that input is always buffered. Changing binmode doesn't effect | |
385 | what's already been read into the buffer. Output is not buffered and | |
386 | changing binmode will have an immediate effect. | |
387 | .IP "\fBbreak\fR \- send \s-1TELNET\s0 break character" 4 | |
388 | .IX Item "break - send TELNET break character" | |
389 | .Vb 1 | |
390 | \& $ok = $obj->break; | |
391 | .Ve | |
392 | .Sp | |
393 | This method sends the \s-1TELNET\s0 break character. This character is | |
394 | provided because it's a signal outside the \s-1ASCII\s0 character set which | |
395 | is currently given local meaning within many systems. It's intended | |
396 | to indicate that the Break Key or the Attention Key was hit. | |
397 | .Sp | |
398 | This method returns \f(CW1\fR on success, or performs the error mode action | |
399 | on failure. | |
400 | .IP "\fBbuffer\fR \- scalar reference to object's input buffer" 4 | |
401 | .IX Item "buffer - scalar reference to object's input buffer" | |
402 | .Vb 1 | |
403 | \& $ref = $obj->buffer; | |
404 | .Ve | |
405 | .Sp | |
406 | This method returns a scalar reference to the input buffer for | |
407 | \&\fI$obj\fR. Data in the input buffer is data that has been read from the | |
408 | remote side but has yet to be read by the user. Modifications to the | |
409 | input buffer are returned by a subsequent read. | |
410 | .IP "\fBbuffer_empty\fR \- discard all data in object's input buffer" 4 | |
411 | .IX Item "buffer_empty - discard all data in object's input buffer" | |
412 | .Vb 1 | |
413 | \& $obj->buffer_empty; | |
414 | .Ve | |
415 | .Sp | |
416 | This method removes all data in the input buffer for \fI$obj\fR. | |
417 | .IP "\fBclose\fR \- close object" 4 | |
418 | .IX Item "close - close object" | |
419 | .Vb 1 | |
420 | \& $ok = $obj->close; | |
421 | .Ve | |
422 | .Sp | |
423 | This method closes the socket, file, or pipe associated with the | |
424 | object. It always returns a value of \f(CW1\fR. | |
425 | .IP "\fBcmd\fR \- issue command and retrieve output" 4 | |
426 | .IX Item "cmd - issue command and retrieve output" | |
427 | .Vb 11 | |
428 | \& $ok = $obj->cmd($string); | |
429 | \& $ok = $obj->cmd(String => $string, | |
430 | \& [Output => $ref,] | |
431 | \& [Cmd_remove_mode => $mode,] | |
432 | \& [Errmode => $mode,] | |
433 | \& [Input_record_separator => $chars,] | |
434 | \& [Ors => $chars,] | |
435 | \& [Output_record_separator => $chars,] | |
436 | \& [Prompt => $match,] | |
437 | \& [Rs => $chars,] | |
438 | \& [Timeout => $secs,]); | |
439 | .Ve | |
440 | .Sp | |
441 | .Vb 11 | |
442 | \& @output = $obj->cmd($string); | |
443 | \& @output = $obj->cmd(String => $string, | |
444 | \& [Output => $ref,] | |
445 | \& [Cmd_remove_mode => $mode,] | |
446 | \& [Errmode => $mode,] | |
447 | \& [Input_record_separator => $chars,] | |
448 | \& [Ors => $chars,] | |
449 | \& [Output_record_separator => $chars,] | |
450 | \& [Prompt => $match,] | |
451 | \& [Rs => $chars,] | |
452 | \& [Timeout => $secs,]); | |
453 | .Ve | |
454 | .Sp | |
455 | This method sends the command \fI$string\fR, and reads the characters | |
456 | sent back by the command up until and including the matching prompt. | |
457 | It's assumed that the program to which you're sending is some kind of | |
458 | command prompting interpreter such as a shell. | |
459 | .Sp | |
460 | The command \fI$string\fR is automatically appended with the | |
461 | output_record_separator, By default that's \f(CW"\en"\fR. This is similar | |
462 | to someone typing a command and hitting the return key. Set the | |
463 | output_record_separator to change this behavior. | |
464 | .Sp | |
465 | In a scalar context, the characters read from the remote side are | |
466 | discarded and \f(CW1\fR is returned on success. On time\-out, eof, or other | |
467 | failures, the error mode action is performed. See \f(CW\*(C`errmode()\*(C'\fR. | |
468 | .Sp | |
469 | In a list context, just the output generated by the command is | |
470 | returned, one line per element. In other words, all the characters in | |
471 | between the echoed back command string and the prompt are returned. | |
472 | If the command happens to return no output, a list containing one | |
473 | element, the empty string is returned. This is so the list will | |
474 | indicate true in a boolean context. On time\-out, eof, or other | |
475 | failures, the error mode action is performed. See \f(CW\*(C`errmode()\*(C'\fR. | |
476 | .Sp | |
477 | The characters that matched the prompt may be retrieved using | |
478 | \&\f(CW\*(C`last_prompt()\*(C'\fR. | |
479 | .Sp | |
480 | Many command interpreters echo back the command sent. In most | |
481 | situations, this method removes the first line returned from the | |
482 | remote side (i.e. the echoed back command). See \f(CW\*(C`cmd_remove_mode()\*(C'\fR | |
483 | for more control over this feature. | |
484 | .Sp | |
485 | Use \f(CW\*(C`dump_log()\*(C'\fR to debug when this method keeps timing-out and you | |
486 | don't think it should. | |
487 | .Sp | |
488 | Consider using a combination of \f(CW\*(C`print()\*(C'\fR and \f(CW\*(C`waitfor()\*(C'\fR as an | |
489 | alternative to this method when it doesn't do what you want, e.g. the | |
490 | command you send prompts for input. | |
491 | .Sp | |
492 | The \fIOutput\fR named parameter provides an alternative method of | |
493 | receiving command output. If you pass a scalar reference, all the | |
494 | output (even if it contains multiple lines) is returned in the | |
495 | referenced scalar. If you pass an array or hash reference, the lines | |
496 | of output are returned in the referenced array or hash. You can use | |
497 | \&\f(CW\*(C`input_record_separator()\*(C'\fR to change the notion of what separates a | |
498 | line. | |
499 | .Sp | |
500 | Optional named parameters are provided to override the current | |
501 | settings of cmd_remove_mode, errmode, input_record_separator, ors, | |
502 | output_record_separator, prompt, rs, and timeout. Rs is synonymous | |
503 | with input_record_separator and ors is synonymous with | |
504 | output_record_separator. | |
505 | .IP "\fBcmd_remove_mode\fR \- toggle removal of echoed commands" 4 | |
506 | .IX Item "cmd_remove_mode - toggle removal of echoed commands" | |
507 | .Vb 1 | |
508 | \& $mode = $obj->cmd_remove_mode; | |
509 | .Ve | |
510 | .Sp | |
511 | .Vb 1 | |
512 | \& $prev = $obj->cmd_remove_mode($mode); | |
513 | .Ve | |
514 | .Sp | |
515 | This method controls how to deal with echoed back commands in the | |
516 | output returned by \fIcmd()\fR. Typically, when you send a command to the | |
517 | remote side, the first line of output returned is the command echoed | |
518 | back. Use this mode to remove the first line of output normally | |
519 | returned by \fIcmd()\fR. | |
520 | .Sp | |
521 | If no argument is given, the current mode is returned. | |
522 | .Sp | |
523 | If \fI$mode\fR is \f(CW0\fR then the command output returned from \fIcmd()\fR has no | |
524 | lines removed. If \fI$mode\fR is a positive integer, then the first | |
525 | \&\fI$mode\fR lines of command output are stripped. | |
526 | .Sp | |
527 | By default, \fI$mode\fR is set to \f(CW"auto"\fR. Auto means that whether or | |
528 | not the first line of command output is stripped, depends on whether | |
529 | or not the remote side offered to echo. By default, Net::Telnet | |
530 | always accepts an offer to echo by the remote side. You can change | |
531 | the default to reject such an offer using \f(CW\*(C`option_accept()\*(C'\fR. | |
532 | .Sp | |
533 | A warning is printed to \s-1STDERR\s0 when attempting to set this attribute | |
534 | to something that's not \f(CW"auto"\fR or a non-negative integer. | |
535 | .IP "\fBdump_log\fR \- log all I/O in dump format" 4 | |
536 | .IX Item "dump_log - log all I/O in dump format" | |
537 | .Vb 1 | |
538 | \& $fh = $obj->dump_log; | |
539 | .Ve | |
540 | .Sp | |
541 | .Vb 1 | |
542 | \& $fh = $obj->dump_log($fh); | |
543 | .Ve | |
544 | .Sp | |
545 | .Vb 1 | |
546 | \& $fh = $obj->dump_log($filename); | |
547 | .Ve | |
548 | .Sp | |
549 | This method starts or stops dump format logging of all the object's | |
550 | input and output. The dump format shows the blocks read and written | |
551 | in a hexadecimal and printable character format. This method is | |
552 | useful when debugging, however you might want to first try | |
553 | \&\f(CW\*(C`input_log()\*(C'\fR as it's more readable. | |
554 | .Sp | |
555 | If no argument is given, the current log filehandle is returned. An | |
556 | empty string indicates logging is off. | |
557 | .Sp | |
558 | To stop logging, use an empty string as an argument. | |
559 | .Sp | |
560 | If an open filehandle is given, it is used for logging and returned. | |
561 | Otherwise, the argument is assumed to be the name of a file, the file | |
562 | is opened and a filehandle to it is returned. If the file can't be | |
563 | opened for writing, the error mode action is performed. | |
564 | .IP "\fBeof\fR \- end of file indicator" 4 | |
565 | .IX Item "eof - end of file indicator" | |
566 | .Vb 1 | |
567 | \& $eof = $obj->eof; | |
568 | .Ve | |
569 | .Sp | |
570 | This method returns \f(CW1\fR if end of file has been read, otherwise it | |
571 | returns an empty string. Because the input is buffered this isn't the | |
572 | same thing as \fI$obj\fR has closed. In other words \fI$obj\fR can be | |
573 | closed but there still can be stuff in the buffer to be read. Under | |
574 | this condition you can still read but you won't be able to write. | |
575 | .IP "\fBerrmode\fR \- define action to be performed on error" 4 | |
576 | .IX Item "errmode - define action to be performed on error" | |
577 | .Vb 1 | |
578 | \& $mode = $obj->errmode; | |
579 | .Ve | |
580 | .Sp | |
581 | .Vb 1 | |
582 | \& $prev = $obj->errmode($mode); | |
583 | .Ve | |
584 | .Sp | |
585 | This method gets or sets the action used when errors are encountered | |
586 | using the object. The first calling sequence returns the current | |
587 | error mode. The second calling sequence sets it to \fI$mode\fR and | |
588 | returns the previous mode. Valid values for \fI$mode\fR are \f(CW"die"\fR | |
589 | (the default), \f(CW"return"\fR, a \fIcoderef\fR, or an \fIarrayref\fR. | |
590 | .Sp | |
591 | When mode is \f(CW"die"\fR and an error is encountered using the object, | |
592 | then an error message is printed to standard error and the program | |
593 | dies. | |
594 | .Sp | |
595 | When mode is \f(CW"return"\fR then the method generating the error places | |
596 | an error message in the object and returns an undefined value in a | |
597 | scalar context and an empty list in list context. The error message | |
598 | may be obtained using \f(CW\*(C`errmsg()\*(C'\fR. | |
599 | .Sp | |
600 | When mode is a \fIcoderef\fR, then when an error is encountered | |
601 | \&\fIcoderef\fR is called with the error message as its first argument. | |
602 | Using this mode you may have your own subroutine handle errors. If | |
603 | \&\fIcoderef\fR itself returns then the method generating the error returns | |
604 | undefined or an empty list depending on context. | |
605 | .Sp | |
606 | When mode is an \fIarrayref\fR, the first element of the array must be a | |
607 | \&\fIcoderef\fR. Any elements that follow are the arguments to \fIcoderef\fR. | |
608 | When an error is encountered, the \fIcoderef\fR is called with its | |
609 | arguments. Using this mode you may have your own subroutine handle | |
610 | errors. If the \fIcoderef\fR itself returns then the method generating | |
611 | the error returns undefined or an empty list depending on context. | |
612 | .Sp | |
613 | A warning is printed to \s-1STDERR\s0 when attempting to set this attribute | |
614 | to something that's not \f(CW"die"\fR, \f(CW"return"\fR, a \fIcoderef\fR, or an | |
615 | \&\fIarrayref\fR whose first element isn't a \fIcoderef\fR. | |
616 | .IP "\fBerrmsg\fR \- most recent error message" 4 | |
617 | .IX Item "errmsg - most recent error message" | |
618 | .Vb 1 | |
619 | \& $msg = $obj->errmsg; | |
620 | .Ve | |
621 | .Sp | |
622 | .Vb 1 | |
623 | \& $prev = $obj->errmsg(@msgs); | |
624 | .Ve | |
625 | .Sp | |
626 | The first calling sequence returns the error message associated with | |
627 | the object. The empty string is returned if no error has been | |
628 | encountered yet. The second calling sequence sets the error message | |
629 | for the object to the concatenation of \fI@msgs\fR and returns the | |
630 | previous error message. Normally, error messages are set internally | |
631 | by a method when an error is encountered. | |
632 | .IP "\fBerror\fR \- perform the error mode action" 4 | |
633 | .IX Item "error - perform the error mode action" | |
634 | .Vb 1 | |
635 | \& $obj->error(@msgs); | |
636 | .Ve | |
637 | .Sp | |
638 | This method concatenates \fI@msgs\fR into a string and places it in the | |
639 | object as the error message. Also see \f(CW\*(C`errmsg()\*(C'\fR. It then performs | |
640 | the error mode action. Also see \f(CW\*(C`errmode()\*(C'\fR. | |
641 | .Sp | |
642 | If the error mode doesn't cause the program to die, then an undefined | |
643 | value or an empty list is returned depending on the context. | |
644 | .Sp | |
645 | This method is primarily used by this class or a sub-class to perform | |
646 | the user requested action when an error is encountered. | |
647 | .IP "\fBfhopen\fR \- use already open filehandle for I/O" 4 | |
648 | .IX Item "fhopen - use already open filehandle for I/O" | |
649 | .Vb 1 | |
650 | \& $ok = $obj->fhopen($fh); | |
651 | .Ve | |
652 | .Sp | |
653 | This method associates the open filehandle \fI$fh\fR with \fI$obj\fR for | |
654 | further I/O. Filehandle \fI$fh\fR must already be opened. | |
655 | .Sp | |
656 | Suppose you want to use the features of this module to do I/O to | |
657 | something other than a \s-1TCP\s0 port, for example \s-1STDIN\s0 or a filehandle | |
658 | opened to read from a process. Instead of opening the object for I/O | |
659 | to a \s-1TCP\s0 port by using \f(CW\*(C`open()\*(C'\fR or \f(CW\*(C`new()\*(C'\fR, call this method | |
660 | instead. | |
661 | .Sp | |
662 | The value \f(CW1\fR is returned success, the error mode action is performed | |
663 | on failure. | |
664 | .IP "\fBget\fR \- read block of data" 4 | |
665 | .IX Item "get - read block of data" | |
666 | .Vb 4 | |
667 | \& $data = $obj->get([Binmode => $mode,] | |
668 | \& [Errmode => $errmode,] | |
669 | \& [Telnetmode => $mode,] | |
670 | \& [Timeout => $secs,]); | |
671 | .Ve | |
672 | .Sp | |
673 | This method reads a block of data from the object and returns it along | |
674 | with any buffered data. If no buffered data is available to return, | |
675 | it will wait for data to read using the timeout specified in the | |
676 | object. You can override that timeout using \fI$secs\fR. Also see | |
677 | \&\f(CW\*(C`timeout()\*(C'\fR. If buffered data is available to return, it also checks | |
678 | for a block of data that can be immediately read. | |
679 | .Sp | |
680 | On eof an undefined value is returned. On time-out or other failures, | |
681 | the error mode action is performed. To distinguish between eof or an | |
682 | error occurring when the error mode is not set to \f(CW"die"\fR, use | |
683 | \&\f(CW\*(C`eof()\*(C'\fR. | |
684 | .Sp | |
685 | Optional named parameters are provided to override the current | |
686 | settings of binmode, errmode, telnetmode, and timeout. | |
687 | .IP "\fBgetline\fR \- read next line" 4 | |
688 | .IX Item "getline - read next line" | |
689 | .Vb 6 | |
690 | \& $line = $obj->getline([Binmode => $mode,] | |
691 | \& [Errmode => $errmode,] | |
692 | \& [Input_record_separator => $chars,] | |
693 | \& [Rs => $chars,] | |
694 | \& [Telnetmode => $mode,] | |
695 | \& [Timeout => $secs,]); | |
696 | .Ve | |
697 | .Sp | |
698 | This method reads and returns the next line of data from the object. | |
699 | You can use \f(CW\*(C`input_record_separator()\*(C'\fR to change the notion of what | |
700 | separates a line. The default is \f(CW"\en"\fR. If a line isn't | |
701 | immediately available, this method blocks waiting for a line or a | |
702 | time\-out. | |
703 | .Sp | |
704 | On eof an undefined value is returned. On time-out or other failures, | |
705 | the error mode action is performed. To distinguish between eof or an | |
706 | error occurring when the error mode is not set to \f(CW"die"\fR, use | |
707 | \&\f(CW\*(C`eof()\*(C'\fR. | |
708 | .Sp | |
709 | Optional named parameters are provided to override the current | |
710 | settings of binmode, errmode, input_record_separator, rs, telnetmode, | |
711 | and timeout. Rs is synonymous with input_record_separator. | |
712 | .IP "\fBgetlines\fR \- read next lines" 4 | |
713 | .IX Item "getlines - read next lines" | |
714 | .Vb 7 | |
715 | \& @lines = $obj->getlines([Binmode => $mode,] | |
716 | \& [Errmode => $errmode,] | |
717 | \& [Input_record_separator => $chars,] | |
718 | \& [Rs => $chars,] | |
719 | \& [Telnetmode => $mode,] | |
720 | \& [Timeout => $secs,] | |
721 | \& [All => $boolean,]); | |
722 | .Ve | |
723 | .Sp | |
724 | This method reads and returns all the lines of data from the object | |
725 | until end of file is read. You can use \f(CW\*(C`input_record_separator()\*(C'\fR to | |
726 | change the notion of what separates a line. The default is \f(CW"\en"\fR. | |
727 | A time-out error occurs if all the lines can't be read within the | |
728 | time-out interval. See \f(CW\*(C`timeout()\*(C'\fR. | |
729 | .Sp | |
730 | The behavior of this method was changed in version 3.03. Prior to | |
731 | version 3.03 this method returned just the lines available from the | |
732 | next read. To get that old behavior, use the optional named parameter | |
733 | \&\fIAll\fR and set \fI$boolean\fR to \f(CW""\fR or \f(CW0\fR. | |
734 | .Sp | |
735 | If only eof is read then an empty list is returned. On time-out or | |
736 | other failures, the error mode action is performed. Use \f(CW\*(C`eof()\*(C'\fR to | |
737 | distinguish between reading only eof or an error occurring when the | |
738 | error mode is not set to \f(CW"die"\fR. | |
739 | .Sp | |
740 | Optional named parameters are provided to override the current | |
741 | settings of binmode, errmode, input_record_separator, rs, telnetmode, | |
742 | and timeout. Rs is synonymous with input_record_separator. | |
743 | .IP "\fBhost\fR \- name of remote host" 4 | |
744 | .IX Item "host - name of remote host" | |
745 | .Vb 1 | |
746 | \& $host = $obj->host; | |
747 | .Ve | |
748 | .Sp | |
749 | .Vb 1 | |
750 | \& $prev = $obj->host($host); | |
751 | .Ve | |
752 | .Sp | |
753 | This method designates the remote host for \f(CW\*(C`open()\*(C'\fR. With no | |
754 | argument it returns the current host name set in the object. With an | |
755 | argument it sets the current host name to \fI$host\fR and returns the | |
756 | previous host name. You may indicate the remote host using either a | |
757 | hostname or an \s-1IP\s0 address. | |
758 | .Sp | |
759 | The default value is \f(CW"localhost"\fR. It may also be set by \f(CW\*(C`open()\*(C'\fR | |
760 | or \f(CW\*(C`new()\*(C'\fR. | |
761 | .IP "\fBinput_log\fR \- log all input" 4 | |
762 | .IX Item "input_log - log all input" | |
763 | .Vb 1 | |
764 | \& $fh = $obj->input_log; | |
765 | .Ve | |
766 | .Sp | |
767 | .Vb 1 | |
768 | \& $fh = $obj->input_log($fh); | |
769 | .Ve | |
770 | .Sp | |
771 | .Vb 1 | |
772 | \& $fh = $obj->input_log($filename); | |
773 | .Ve | |
774 | .Sp | |
775 | This method starts or stops logging of input. This is useful when | |
776 | debugging. Also see \f(CW\*(C`dump_log()\*(C'\fR. Because most command interpreters | |
777 | echo back commands received, it's likely all your output will also be | |
778 | in this log. Note that input logging occurs after newline | |
779 | translation. See \f(CW\*(C`binmode()\*(C'\fR for details on newline translation. | |
780 | .Sp | |
781 | If no argument is given, the log filehandle is returned. An empty | |
782 | string indicates logging is off. | |
783 | .Sp | |
784 | To stop logging, use an empty string as an argument. | |
785 | .Sp | |
786 | If an open filehandle is given, it is used for logging and returned. | |
787 | Otherwise, the argument is assumed to be the name of a file, the file | |
788 | is opened for logging and a filehandle to it is returned. If the file | |
789 | can't be opened for writing, the error mode action is performed. | |
790 | .IP "\fBinput_record_separator\fR \- input line delimiter" 4 | |
791 | .IX Item "input_record_separator - input line delimiter" | |
792 | .Vb 1 | |
793 | \& $chars = $obj->input_record_separator; | |
794 | .Ve | |
795 | .Sp | |
796 | .Vb 1 | |
797 | \& $prev = $obj->input_record_separator($chars); | |
798 | .Ve | |
799 | .Sp | |
800 | This method designates the line delimiter for input. It's used with | |
801 | \&\f(CW\*(C`getline()\*(C'\fR, \f(CW\*(C`getlines()\*(C'\fR, and \f(CW\*(C`cmd()\*(C'\fR to determine lines in the | |
802 | input. | |
803 | .Sp | |
804 | With no argument this method returns the current input record | |
805 | separator set in the object. With an argument it sets the input | |
806 | record separator to \fI$chars\fR and returns the previous value. Note | |
807 | that \fI$chars\fR must have length. | |
808 | .Sp | |
809 | A warning is printed to \s-1STDERR\s0 when attempting to set this attribute | |
810 | to a string with no length. | |
811 | .IP "\fBlast_prompt\fR \- last prompt read" 4 | |
812 | .IX Item "last_prompt - last prompt read" | |
813 | .Vb 1 | |
814 | \& $string = $obj->last_prompt; | |
815 | .Ve | |
816 | .Sp | |
817 | .Vb 1 | |
818 | \& $prev = $obj->last_prompt($string); | |
819 | .Ve | |
820 | .Sp | |
821 | With no argument this method returns the last prompt read by \fIcmd()\fR or | |
822 | \&\fIlogin()\fR. See \f(CW\*(C`prompt()\*(C'\fR. With an argument it sets the last prompt | |
823 | read to \fI$string\fR and returns the previous value. Normally, only | |
824 | internal methods set the last prompt. | |
825 | .IP "\fBlastline\fR \- last line read" 4 | |
826 | .IX Item "lastline - last line read" | |
827 | .Vb 1 | |
828 | \& $line = $obj->lastline; | |
829 | .Ve | |
830 | .Sp | |
831 | .Vb 1 | |
832 | \& $prev = $obj->lastline($line); | |
833 | .Ve | |
834 | .Sp | |
835 | This method retrieves the last line read from the object. This may be | |
836 | a useful error message when the remote side abnormally closes the | |
837 | connection. Typically the remote side will print an error message | |
838 | before closing. | |
839 | .Sp | |
840 | With no argument this method returns the last line read from the | |
841 | object. With an argument it sets the last line read to \fI$line\fR and | |
842 | returns the previous value. Normally, only internal methods set the | |
843 | last line. | |
844 | .IP "\fBlogin\fR \- perform standard login" 4 | |
845 | .IX Item "login - perform standard login" | |
846 | .Vb 1 | |
847 | \& $ok = $obj->login($username, $password); | |
848 | .Ve | |
849 | .Sp | |
850 | .Vb 5 | |
851 | \& $ok = $obj->login(Name => $username, | |
852 | \& Password => $password, | |
853 | \& [Errmode => $mode,] | |
854 | \& [Prompt => $match,] | |
855 | \& [Timeout => $secs,]); | |
856 | .Ve | |
857 | .Sp | |
858 | This method performs a standard login by waiting for a login prompt | |
859 | and responding with \fI$username\fR, then waiting for the password prompt | |
860 | and responding with \fI$password\fR, and then waiting for the command | |
861 | interpreter prompt. If any of those prompts sent by the remote side | |
862 | don't match what's expected, this method will time\-out, unless timeout | |
863 | is turned off. | |
864 | .Sp | |
865 | Login prompt must match either of these case insensitive patterns: | |
866 | .Sp | |
867 | .Vb 2 | |
868 | \& /login[: ]*$/i | |
869 | \& /username[: ]*$/i | |
870 | .Ve | |
871 | .Sp | |
872 | Password prompt must match this case insensitive pattern: | |
873 | .Sp | |
874 | .Vb 1 | |
875 | \& /password[: ]*$/i | |
876 | .Ve | |
877 | .Sp | |
878 | The command interpreter prompt must match the current setting of | |
879 | prompt. See \f(CW\*(C`prompt()\*(C'\fR. | |
880 | .Sp | |
881 | Use \f(CW\*(C`dump_log()\*(C'\fR to debug when this method keeps timing-out and you | |
882 | don't think it should. | |
883 | .Sp | |
884 | Consider using a combination of \f(CW\*(C`print()\*(C'\fR and \f(CW\*(C`waitfor()\*(C'\fR as an | |
885 | alternative to this method when it doesn't do what you want, e.g. the | |
886 | remote host doesn't prompt for a username. | |
887 | .Sp | |
888 | On success, \f(CW1\fR is returned. On time out, eof, or other failures, | |
889 | the error mode action is performed. See \f(CW\*(C`errmode()\*(C'\fR. | |
890 | .Sp | |
891 | Optional named parameters are provided to override the current | |
892 | settings of errmode, prompt, and timeout. | |
893 | .IP "\fBmax_buffer_length\fR \- maximum size of input buffer" 4 | |
894 | .IX Item "max_buffer_length - maximum size of input buffer" | |
895 | .Vb 1 | |
896 | \& $len = $obj->max_buffer_length; | |
897 | .Ve | |
898 | .Sp | |
899 | .Vb 1 | |
900 | \& $prev = $obj->max_buffer_length($len); | |
901 | .Ve | |
902 | .Sp | |
903 | This method designates the maximum size of the input buffer. An error | |
904 | is generated when a read causes the buffer to exceed this limit. The | |
905 | default value is 1,048,576 bytes (1MB). The input buffer can grow | |
906 | much larger than the block size when you continuously read using | |
907 | \&\f(CW\*(C`getline()\*(C'\fR or \f(CW\*(C`waitfor()\*(C'\fR and the data stream contains no newlines | |
908 | or matching waitfor patterns. | |
909 | .Sp | |
910 | With no argument, this method returns the current maximum buffer | |
911 | length set in the object. With an argument it sets the maximum buffer | |
912 | length to \fI$len\fR and returns the previous value. Values of \fI$len\fR | |
913 | smaller than 512 will be adjusted to 512. | |
914 | .Sp | |
915 | A warning is printed to \s-1STDERR\s0 when attempting to set this attribute | |
916 | to something that isn't a positive integer. | |
917 | .IP "\fBofs\fR \- field separator for print" 4 | |
918 | .IX Item "ofs - field separator for print" | |
919 | .Vb 1 | |
920 | \& $chars = $obj->ofs | |
921 | .Ve | |
922 | .Sp | |
923 | .Vb 1 | |
924 | \& $prev = $obj->ofs($chars); | |
925 | .Ve | |
926 | .Sp | |
927 | This method is synonymous with \f(CW\*(C`output_field_separator()\*(C'\fR. | |
928 | .IP "\fBopen\fR \- connect to port on remote host" 4 | |
929 | .IX Item "open - connect to port on remote host" | |
930 | .Vb 1 | |
931 | \& $ok = $obj->open($host); | |
932 | .Ve | |
933 | .Sp | |
934 | .Vb 4 | |
935 | \& $ok = $obj->open([Host => $host,] | |
936 | \& [Port => $port,] | |
937 | \& [Errmode => $mode,] | |
938 | \& [Timeout => $secs,]); | |
939 | .Ve | |
940 | .Sp | |
941 | This method opens a \s-1TCP\s0 connection to \fI$port\fR on \fI$host\fR. If either | |
942 | argument is missing then the current value of \f(CW\*(C`host()\*(C'\fR or \f(CW\*(C`port()\*(C'\fR | |
943 | is used. Optional named parameters are provided to override the | |
944 | current setting of errmode and timeout. | |
945 | .Sp | |
946 | On success \f(CW1\fR is returned. On time-out or other connection | |
947 | failures, the error mode action is performed. See \f(CW\*(C`errmode()\*(C'\fR. | |
948 | .Sp | |
949 | Time-outs don't work for this method on machines that don't implement | |
950 | \&\s-1SIGALRM\s0 \- most notably MS-Windows machines. For those machines, an | |
951 | error is returned when the system reaches its own time-out while | |
952 | trying to connect. | |
953 | .Sp | |
954 | A side effect of this method is to reset the alarm interval associated | |
955 | with \s-1SIGALRM\s0. | |
956 | .IP "\fBoption_accept\fR \- indicate willingness to accept a \s-1TELNET\s0 option" 4 | |
957 | .IX Item "option_accept - indicate willingness to accept a TELNET option" | |
958 | .Vb 4 | |
959 | \& $fh = $obj->option_accept([Do => $telopt,] | |
960 | \& [Dont => $telopt,] | |
961 | \& [Will => $telopt,] | |
962 | \& [Wont => $telopt,]); | |
963 | .Ve | |
964 | .Sp | |
965 | This method is used to indicate whether to accept or reject an offer | |
966 | to enable a \s-1TELNET\s0 option made by the remote side. If you're using | |
967 | \&\fIDo\fR or \fIWill\fR to indicate a willingness to enable, then a | |
968 | notification callback must have already been defined by a prior call | |
969 | to \f(CW\*(C`option_callback()\*(C'\fR. See \f(CW\*(C`option_callback()\*(C'\fR for details on | |
970 | receiving enable/disable notification of a \s-1TELNET\s0 option. | |
971 | .Sp | |
972 | You can give multiple \fIDo\fR, \fIDont\fR, \fIWill\fR, or \fIWont\fR arguments | |
973 | for different \s-1TELNET\s0 options in the same call to this method. | |
974 | .Sp | |
975 | The following example describes the meaning of the named parameters. | |
976 | A \s-1TELNET\s0 option, such as \f(CW\*(C`TELOPT_ECHO\*(C'\fR used below, is an integer | |
977 | constant that you can import from Net::Telnet. See the source in file | |
978 | Telnet.pm for the complete list. | |
979 | .RS 4 | |
980 | .IP "\(bu" 4 | |
981 | \&\fIDo\fR => \f(CW\*(C`TELOPT_ECHO\*(C'\fR | |
982 | .RS 4 | |
983 | .IP "\(bu" 4 | |
984 | we'll accept an offer to enable the echo option on the local side | |
985 | .RE | |
986 | .RS 4 | |
987 | .RE | |
988 | .IP "\(bu" 4 | |
989 | \&\fIDont\fR => \f(CW\*(C`TELOPT_ECHO\*(C'\fR | |
990 | .RS 4 | |
991 | .IP "\(bu" 4 | |
992 | we'll reject an offer to enable the echo option on the local side | |
993 | .RE | |
994 | .RS 4 | |
995 | .RE | |
996 | .IP "\(bu" 4 | |
997 | \&\fIWill\fR => \f(CW\*(C`TELOPT_ECHO\*(C'\fR | |
998 | .RS 4 | |
999 | .IP "\(bu" 4 | |
1000 | we'll accept an offer to enable the echo option on the remote side | |
1001 | .RE | |
1002 | .RS 4 | |
1003 | .RE | |
1004 | .IP "\(bu" 4 | |
1005 | \&\fIWont\fR => \f(CW\*(C`TELOPT_ECHO\*(C'\fR | |
1006 | .RS 4 | |
1007 | .IP "\(bu" 4 | |
1008 | we'll reject an offer to enable the echo option on the remote side | |
1009 | .RE | |
1010 | .RS 4 | |
1011 | .RE | |
1012 | .RE | |
1013 | .RS 4 | |
1014 | .RE | |
1015 | .IP "\(bu" 4 | |
1016 | Use \f(CW\*(C`option_send()\*(C'\fR to send a request to the remote side to enable or | |
1017 | disable a particular \s-1TELNET\s0 option. | |
1018 | .IP "\fBoption_callback\fR \- define the option negotiation callback" 4 | |
1019 | .IX Item "option_callback - define the option negotiation callback" | |
1020 | .Vb 1 | |
1021 | \& $coderef = $obj->option_callback; | |
1022 | .Ve | |
1023 | .Sp | |
1024 | .Vb 1 | |
1025 | \& $prev = $obj->option_callback($coderef); | |
1026 | .Ve | |
1027 | .Sp | |
1028 | This method defines the callback subroutine that's called when a | |
1029 | \&\s-1TELNET\s0 option is enabled or disabled. Once defined, the | |
1030 | \&\fIoption_callback\fR may not be undefined. However, calling this method | |
1031 | with a different \fI$coderef\fR changes it. | |
1032 | .Sp | |
1033 | A warning is printed to \s-1STDERR\s0 when attempting to set this attribute | |
1034 | to something that isn't a coderef. | |
1035 | .Sp | |
1036 | Here are the circumstances that invoke \fI$coderef\fR: | |
1037 | .RS 4 | |
1038 | .IP "\(bu" 4 | |
1039 | An option becomes enabled because the remote side requested an enable | |
1040 | and \f(CW\*(C`option_accept()\*(C'\fR had been used to arrange that it be accepted. | |
1041 | .IP "\(bu" 4 | |
1042 | The remote side arbitrarily decides to disable an option that is | |
1043 | currently enabled. Note that Net::Telnet always accepts a request to | |
1044 | disable from the remote side. | |
1045 | .IP "\(bu" 4 | |
1046 | \&\f(CW\*(C`option_send()\*(C'\fR was used to send a request to enable or disable an | |
1047 | option and the response from the remote side has just been received. | |
1048 | Note, that if a request to enable is rejected then \fI$coderef\fR is | |
1049 | still invoked even though the option didn't change. | |
1050 | .RE | |
1051 | .RS 4 | |
1052 | .RE | |
1053 | .IP "\(bu" 4 | |
1054 | Here are the arguments passed to \fI&$coderef\fR: | |
1055 | .Sp | |
1056 | .Vb 2 | |
1057 | \& &$coderef($obj, $option, $is_remote, | |
1058 | \& $is_enabled, $was_enabled, $buf_position); | |
1059 | .Ve | |
1060 | .RS 4 | |
1061 | .IP "\(bu" 4 | |
1062 | 1. \fI$obj\fR is the Net::Telnet object | |
1063 | .IP "\(bu" 4 | |
1064 | 2. \fI$option\fR is the \s-1TELNET\s0 option. Net::Telnet exports constants | |
1065 | for the various \s-1TELNET\s0 options which just equate to an integer. | |
1066 | .IP "\(bu" 4 | |
1067 | 3. \fI$is_remote\fR is a boolean indicating for which side the option | |
1068 | applies. | |
1069 | .IP "\(bu" 4 | |
1070 | 4. \fI$is_enabled\fR is a boolean indicating the option is enabled or | |
1071 | disabled | |
1072 | .IP "\(bu" 4 | |
1073 | 5. \fI$was_enabled\fR is a boolean indicating the option was previously | |
1074 | enabled or disabled | |
1075 | .IP "\(bu" 4 | |
1076 | 6. \fI$buf_position\fR is an integer indicating the position in the | |
1077 | object's input buffer where the option takes effect. See \f(CW\*(C`buffer()\*(C'\fR | |
1078 | to access the object's input buffer. | |
1079 | .RE | |
1080 | .RS 4 | |
1081 | .RE | |
1082 | .IP "\fBoption_log\fR \- log all \s-1TELNET\s0 options sent or received" 4 | |
1083 | .IX Item "option_log - log all TELNET options sent or received" | |
1084 | .Vb 1 | |
1085 | \& $fh = $obj->option_log; | |
1086 | .Ve | |
1087 | .Sp | |
1088 | .Vb 1 | |
1089 | \& $fh = $obj->option_log($fh); | |
1090 | .Ve | |
1091 | .Sp | |
1092 | .Vb 1 | |
1093 | \& $fh = $obj->option_log($filename); | |
1094 | .Ve | |
1095 | .Sp | |
1096 | This method starts or stops logging of all \s-1TELNET\s0 options being sent | |
1097 | or received. This is useful for debugging when you send options via | |
1098 | \&\f(CW\*(C`option_send()\*(C'\fR or you arrange to accept option requests from the | |
1099 | remote side via \f(CW\*(C`option_accept()\*(C'\fR. Also see \f(CW\*(C`dump_log()\*(C'\fR. | |
1100 | .Sp | |
1101 | If no argument is given, the log filehandle is returned. An empty | |
1102 | string indicates logging is off. | |
1103 | .Sp | |
1104 | To stop logging, use an empty string as an argument. | |
1105 | .Sp | |
1106 | If an open filehandle is given, it is used for logging and returned. | |
1107 | Otherwise, the argument is assumed to be the name of a file, the file | |
1108 | is opened for logging and a filehandle to it is returned. If the file | |
1109 | can't be opened for writing, the error mode action is performed. | |
1110 | .IP "\fBoption_send\fR \- send \s-1TELNET\s0 option negotiation request" 4 | |
1111 | .IX Item "option_send - send TELNET option negotiation request" | |
1112 | .Vb 5 | |
1113 | \& $ok = $obj->option_send([Do => $telopt,] | |
1114 | \& [Dont => $telopt,] | |
1115 | \& [Will => $telopt,] | |
1116 | \& [Wont => $telopt,] | |
1117 | \& [Async => $boolean,]); | |
1118 | .Ve | |
1119 | .Sp | |
1120 | This method is not yet implemented. Look for it in a future version. | |
1121 | .IP "\fBoption_state\fR \- get current state of a \s-1TELNET\s0 option" 4 | |
1122 | .IX Item "option_state - get current state of a TELNET option" | |
1123 | .Vb 1 | |
1124 | \& $hashref = $obj->option_state($telopt); | |
1125 | .Ve | |
1126 | .Sp | |
1127 | This method returns a hashref containing a copy of the current state | |
1128 | of \s-1TELNET\s0 option \fI$telopt\fR. | |
1129 | .Sp | |
1130 | Here are the values returned in the hash: | |
1131 | .RS 4 | |
1132 | .IP "\(bu" 4 | |
1133 | \&\fI$hashref\fR\->{remote_enabled} | |
1134 | .RS 4 | |
1135 | .IP "\(bu" 4 | |
1136 | boolean that indicates if the option is enabled on the remote side. | |
1137 | .RE | |
1138 | .RS 4 | |
1139 | .RE | |
1140 | .IP "\(bu" 4 | |
1141 | \&\fI$hashref\fR\->{remote_enable_ok} | |
1142 | .RS 4 | |
1143 | .IP "\(bu" 4 | |
1144 | boolean that indicates if it's ok to accept an offer to enable this | |
1145 | option on the remote side. | |
1146 | .RE | |
1147 | .RS 4 | |
1148 | .RE | |
1149 | .IP "\(bu" 4 | |
1150 | \&\fI$hashref\fR\->{remote_state} | |
1151 | .RS 4 | |
1152 | .IP "\(bu" 4 | |
1153 | string used to hold the internal state of option negotiation for this | |
1154 | option on the remote side. | |
1155 | .RE | |
1156 | .RS 4 | |
1157 | .RE | |
1158 | .IP "\(bu" 4 | |
1159 | \&\fI$hashref\fR\->{local_enabled} | |
1160 | .RS 4 | |
1161 | .IP "\(bu" 4 | |
1162 | boolean that indicates if the option is enabled on the local side. | |
1163 | .RE | |
1164 | .RS 4 | |
1165 | .RE | |
1166 | .IP "\(bu" 4 | |
1167 | \&\fI$hashref\fR\->{local_enable_ok} | |
1168 | .RS 4 | |
1169 | .IP "\(bu" 4 | |
1170 | boolean that indicates if it's ok to accept an offer to enable this | |
1171 | option on the local side. | |
1172 | .RE | |
1173 | .RS 4 | |
1174 | .RE | |
1175 | .IP "\(bu" 4 | |
1176 | \&\fI$hashref\fR\->{local_state} | |
1177 | .RS 4 | |
1178 | .IP "\(bu" 4 | |
1179 | string used to hold the internal state of option negotiation for this | |
1180 | option on the local side. | |
1181 | .RE | |
1182 | .RS 4 | |
1183 | .RE | |
1184 | .RE | |
1185 | .RS 4 | |
1186 | .RE | |
1187 | .IP "\fBors\fR \- output line delimiter" 4 | |
1188 | .IX Item "ors - output line delimiter" | |
1189 | .Vb 1 | |
1190 | \& $chars = $obj->ors; | |
1191 | .Ve | |
1192 | .Sp | |
1193 | .Vb 1 | |
1194 | \& $prev = $obj->ors($chars); | |
1195 | .Ve | |
1196 | .Sp | |
1197 | This method is synonymous with \f(CW\*(C`output_record_separator()\*(C'\fR. | |
1198 | .IP "\fBoutput_field_separator\fR \- field separator for print" 4 | |
1199 | .IX Item "output_field_separator - field separator for print" | |
1200 | .Vb 1 | |
1201 | \& $chars = $obj->output_field_separator; | |
1202 | .Ve | |
1203 | .Sp | |
1204 | .Vb 1 | |
1205 | \& $prev = $obj->output_field_separator($chars); | |
1206 | .Ve | |
1207 | .Sp | |
1208 | This method designates the output field separator for \f(CW\*(C`print()\*(C'\fR. | |
1209 | Ordinarily the print method simply prints out the comma separated | |
1210 | fields you specify. Set this to specify what's printed between | |
1211 | fields. | |
1212 | .Sp | |
1213 | With no argument this method returns the current output field | |
1214 | separator set in the object. With an argument it sets the output | |
1215 | field separator to \fI$chars\fR and returns the previous value. | |
1216 | .Sp | |
1217 | By default it's set to an empty string. | |
1218 | .IP "\fBoutput_log\fR \- log all output" 4 | |
1219 | .IX Item "output_log - log all output" | |
1220 | .Vb 1 | |
1221 | \& $fh = $obj->output_log; | |
1222 | .Ve | |
1223 | .Sp | |
1224 | .Vb 1 | |
1225 | \& $fh = $obj->output_log($fh); | |
1226 | .Ve | |
1227 | .Sp | |
1228 | .Vb 1 | |
1229 | \& $fh = $obj->output_log($filename); | |
1230 | .Ve | |
1231 | .Sp | |
1232 | This method starts or stops logging of output. This is useful when | |
1233 | debugging. Also see \f(CW\*(C`dump_log()\*(C'\fR. Because most command interpreters | |
1234 | echo back commands received, it's likely all your output would also be | |
1235 | in an input log. See \f(CW\*(C`input_log()\*(C'\fR. Note that output logging occurs | |
1236 | before newline translation. See \f(CW\*(C`binmode()\*(C'\fR for details on newline | |
1237 | translation. | |
1238 | .Sp | |
1239 | If no argument is given, the log filehandle is returned. An empty | |
1240 | string indicates logging is off. | |
1241 | .Sp | |
1242 | To stop logging, use an empty string as an argument. | |
1243 | .Sp | |
1244 | If an open filehandle is given, it is used for logging and returned. | |
1245 | Otherwise, the argument is assumed to be the name of a file, the file | |
1246 | is opened for logging and a filehandle to it is returned. If the file | |
1247 | can't be opened for writing, the error mode action is performed. | |
1248 | .IP "\fBoutput_record_separator\fR \- output line delimiter" 4 | |
1249 | .IX Item "output_record_separator - output line delimiter" | |
1250 | .Vb 1 | |
1251 | \& $chars = $obj->output_record_separator; | |
1252 | .Ve | |
1253 | .Sp | |
1254 | .Vb 1 | |
1255 | \& $prev = $obj->output_record_separator($chars); | |
1256 | .Ve | |
1257 | .Sp | |
1258 | This method designates the output line delimiter for \f(CW\*(C`print()\*(C'\fR and | |
1259 | \&\f(CW\*(C`cmd()\*(C'\fR. Set this to specify what's printed at the end of \f(CW\*(C`print()\*(C'\fR | |
1260 | and \f(CW\*(C`cmd()\*(C'\fR. | |
1261 | .Sp | |
1262 | The output record separator is set to \f(CW"\en"\fR by default, so there's | |
1263 | no need to append all your commands with a newline. To avoid printing | |
1264 | the output_record_separator use \f(CW\*(C`put()\*(C'\fR or set the | |
1265 | output_record_separator to an empty string. | |
1266 | .Sp | |
1267 | With no argument this method returns the current output record | |
1268 | separator set in the object. With an argument it sets the output | |
1269 | record separator to \fI$chars\fR and returns the previous value. | |
1270 | .IP "\fBport\fR \- remote port" 4 | |
1271 | .IX Item "port - remote port" | |
1272 | .Vb 1 | |
1273 | \& $port = $obj->port; | |
1274 | .Ve | |
1275 | .Sp | |
1276 | .Vb 1 | |
1277 | \& $prev = $obj->port($port); | |
1278 | .Ve | |
1279 | .Sp | |
1280 | This method designates the remote \s-1TCP\s0 port. With no argument this | |
1281 | method returns the current port number. With an argument it sets the | |
1282 | current port number to \fI$port\fR and returns the previous port. If | |
1283 | \&\fI$port\fR is a \s-1TCP\s0 service name, then it's first converted to a port | |
1284 | number using the perl function \f(CW\*(C`getservbyname()\*(C'\fR. | |
1285 | .Sp | |
1286 | The default value is \f(CW23\fR. It may also be set by \f(CW\*(C`open()\*(C'\fR or | |
1287 | \&\f(CW\*(C`new()\*(C'\fR. | |
1288 | .Sp | |
1289 | A warning is printed to \s-1STDERR\s0 when attempting to set this attribute | |
1290 | to something that's not a positive integer or a valid \s-1TCP\s0 service | |
1291 | name. | |
1292 | .IP "\fBprint\fR \- write to object" 4 | |
1293 | .IX Item "print - write to object" | |
1294 | .Vb 1 | |
1295 | \& $ok = $obj->print(@list); | |
1296 | .Ve | |
1297 | .Sp | |
1298 | This method writes \fI@list\fR followed by the \fIoutput_record_separator\fR | |
1299 | to the open object and returns \f(CW1\fR if all data was successfully | |
1300 | written. On time-out or other failures, the error mode action is | |
1301 | performed. See \f(CW\*(C`errmode()\*(C'\fR. | |
1302 | .Sp | |
1303 | By default, the \f(CW\*(C`output_record_separator()\*(C'\fR is set to \f(CW"\en"\fR so all | |
1304 | your commands automatically end with a newline. In most cases your | |
1305 | output is being read by a command interpreter which won't accept a | |
1306 | command until newline is read. This is similar to someone typing a | |
1307 | command and hitting the return key. To avoid printing a trailing | |
1308 | \&\f(CW"\en"\fR use \f(CW\*(C`put()\*(C'\fR instead or set the output_record_separator to an | |
1309 | empty string. | |
1310 | .Sp | |
1311 | On failure, it's possible that some data was written. If you choose | |
1312 | to try and recover from a print timing\-out, use \f(CW\*(C`print_length()\*(C'\fR to | |
1313 | determine how much was written before the error occurred. | |
1314 | .Sp | |
1315 | You may also use the output field separator to print a string between | |
1316 | the list elements. See \f(CW\*(C`output_field_separator()\*(C'\fR. | |
1317 | .IP "\fBprint_length\fR \- number of bytes written by print" 4 | |
1318 | .IX Item "print_length - number of bytes written by print" | |
1319 | .Vb 1 | |
1320 | \& $num = $obj->print_length; | |
1321 | .Ve | |
1322 | .Sp | |
1323 | This returns the number of bytes successfully written by the most | |
1324 | recent \f(CW\*(C`print()\*(C'\fR or \f(CW\*(C`put()\*(C'\fR. | |
1325 | .IP "\fBprompt\fR \- pattern to match a prompt" 4 | |
1326 | .IX Item "prompt - pattern to match a prompt" | |
1327 | .Vb 1 | |
1328 | \& $matchop = $obj->prompt; | |
1329 | .Ve | |
1330 | .Sp | |
1331 | .Vb 1 | |
1332 | \& $prev = $obj->prompt($matchop); | |
1333 | .Ve | |
1334 | .Sp | |
1335 | This method sets the pattern used to find a prompt in the input | |
1336 | stream. It must be a string representing a valid perl pattern match | |
1337 | operator. The methods \f(CW\*(C`login()\*(C'\fR and \f(CW\*(C`cmd()\*(C'\fR try to read until | |
1338 | matching the prompt. They will fail with a time-out error if the | |
1339 | pattern you've chosen doesn't match what the remote side sends. | |
1340 | .Sp | |
1341 | With no argument this method returns the prompt set in the object. | |
1342 | With an argument it sets the prompt to \fI$matchop\fR and returns the | |
1343 | previous value. | |
1344 | .Sp | |
1345 | The default prompt is \f(CW'/[\e$%#>] $/'\fR | |
1346 | .Sp | |
1347 | Always use single quotes, instead of double quotes, to construct | |
1348 | \&\fI$matchop\fR (e.g. \f(CW'/bash\e$ $/'\fR). If you're constructing a \s-1DOS\s0 like | |
1349 | file path, you'll need to use four backslashes to represent one | |
1350 | (e.g. \f(CW'/c:\e\e\e\eusers\e\e\e\ebill>$/i'\fR). | |
1351 | .Sp | |
1352 | Of course don't forget about regexp metacharacters like \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`[\*(C'\fR, or | |
1353 | \&\f(CW\*(C`$\*(C'\fR. You'll only need a single backslash to quote them. The anchor | |
1354 | metacharacters \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR refer to positions in the input buffer. | |
1355 | .Sp | |
1356 | A warning is printed to \s-1STDERR\s0 when attempting to set this attribute | |
1357 | with a match operator missing its opening delimiter. | |
1358 | .IP "\fBput\fR \- write to object" 4 | |
1359 | .IX Item "put - write to object" | |
1360 | .Vb 1 | |
1361 | \& $ok = $obj->put($string); | |
1362 | .Ve | |
1363 | .Sp | |
1364 | .Vb 5 | |
1365 | \& $ok = $obj->put(String => $string, | |
1366 | \& [Binmode => $mode,] | |
1367 | \& [Errmode => $errmode,] | |
1368 | \& [Telnetmode => $mode,] | |
1369 | \& [Timeout => $secs,]); | |
1370 | .Ve | |
1371 | .Sp | |
1372 | This method writes \fI$string\fR to the opened object and returns \f(CW1\fR if | |
1373 | all data was successfully written. This method is like \f(CW\*(C`print()\*(C'\fR | |
1374 | except that it doesn't write the trailing output_record_separator | |
1375 | (\*(L"\en\*(R" by default). On time-out or other failures, the error mode | |
1376 | action is performed. See \f(CW\*(C`errmode()\*(C'\fR. | |
1377 | .Sp | |
1378 | On failure, it's possible that some data was written. If you choose | |
1379 | to try and recover from a put timing\-out, use \f(CW\*(C`print_length()\*(C'\fR to | |
1380 | determine how much was written before the error occurred. | |
1381 | .Sp | |
1382 | Optional named parameters are provided to override the current | |
1383 | settings of binmode, errmode, telnetmode, and timeout. | |
1384 | .IP "\fBrs\fR \- input line delimiter" 4 | |
1385 | .IX Item "rs - input line delimiter" | |
1386 | .Vb 1 | |
1387 | \& $chars = $obj->rs; | |
1388 | .Ve | |
1389 | .Sp | |
1390 | .Vb 1 | |
1391 | \& $prev = $obj->rs($chars); | |
1392 | .Ve | |
1393 | .Sp | |
1394 | This method is synonymous with \f(CW\*(C`input_record_separator()\*(C'\fR. | |
1395 | .IP "\fBtelnetmode\fR \- turn off/on telnet command interpretation" 4 | |
1396 | .IX Item "telnetmode - turn off/on telnet command interpretation" | |
1397 | .Vb 1 | |
1398 | \& $mode = $obj->telnetmode; | |
1399 | .Ve | |
1400 | .Sp | |
1401 | .Vb 1 | |
1402 | \& $prev = $obj->telnetmode($mode); | |
1403 | .Ve | |
1404 | .Sp | |
1405 | This method controls whether or not \s-1TELNET\s0 commands in the data stream | |
1406 | are recognized and handled. The \s-1TELNET\s0 protocol uses certain | |
1407 | character sequences sent in the data stream to control the session. | |
1408 | If the port you're connecting to isn't using the \s-1TELNET\s0 protocol, then | |
1409 | you should turn this mode off. The default is \fIon\fR. | |
1410 | .Sp | |
1411 | If no argument is given, the current mode is returned. | |
1412 | .Sp | |
1413 | If \fI$mode\fR is \f(CW0\fR then telnet mode is off. If \fI$mode\fR is \f(CW1\fR then | |
1414 | telnet mode is on. | |
1415 | .IP "\fBtimed_out\fR \- time-out indicator" 4 | |
1416 | .IX Item "timed_out - time-out indicator" | |
1417 | .Vb 1 | |
1418 | \& $boolean = $obj->timed_out; | |
1419 | .Ve | |
1420 | .Sp | |
1421 | .Vb 1 | |
1422 | \& $prev = $obj->timed_out($boolean); | |
1423 | .Ve | |
1424 | .Sp | |
1425 | This method indicates if a previous read, write, or open method | |
1426 | timed\-out. Remember that timing-out is itself an error. To be able | |
1427 | to invoke \f(CW\*(C`timed_out()\*(C'\fR after a time-out error, you'd have to change | |
1428 | the default error mode to something other than \f(CW"die"\fR. See | |
1429 | \&\f(CW\*(C`errmode()\*(C'\fR. | |
1430 | .Sp | |
1431 | With no argument this method returns \f(CW1\fR if the previous method | |
1432 | timed\-out. With an argument it sets the indicator. Normally, only | |
1433 | internal methods set this indicator. | |
1434 | .IP "\fBtimeout\fR \- I/O time-out interval" 4 | |
1435 | .IX Item "timeout - I/O time-out interval" | |
1436 | .Vb 1 | |
1437 | \& $secs = $obj->timeout; | |
1438 | .Ve | |
1439 | .Sp | |
1440 | .Vb 1 | |
1441 | \& $prev = $obj->timeout($secs); | |
1442 | .Ve | |
1443 | .Sp | |
1444 | This method sets the timeout interval that's used when performing I/O | |
1445 | or connecting to a port. When a method doesn't complete within the | |
1446 | timeout interval then it's an error and the error mode action is | |
1447 | performed. | |
1448 | .Sp | |
1449 | A timeout may be expressed as a relative or absolute value. If | |
1450 | \&\fI$secs\fR is greater than or equal to the time the program started, as | |
1451 | determined by $^T, then it's an absolute time value for when time-out | |
1452 | occurs. The perl function \f(CW\*(C`time()\*(C'\fR may be used to obtain an absolute | |
1453 | time value. For a relative time-out value less than $^T, time-out | |
1454 | happens \fI$secs\fR from when the method begins. | |
1455 | .Sp | |
1456 | If \fI$secs\fR is \f(CW0\fR then time-out occurs if the data cannot be | |
1457 | immediately read or written. Use the undefined value to turn off | |
1458 | timing-out completely. | |
1459 | .Sp | |
1460 | With no argument this method returns the timeout set in the object. | |
1461 | With an argument it sets the timeout to \fI$secs\fR and returns the | |
1462 | previous value. The default timeout value is \f(CW10\fR seconds. | |
1463 | .Sp | |
1464 | A warning is printed to \s-1STDERR\s0 when attempting to set this attribute | |
1465 | to something that's not an \f(CW\*(C`undef\*(C'\fR or a non-negative integer. | |
1466 | .IP "\fBwaitfor\fR \- wait for pattern in the input" 4 | |
1467 | .IX Item "waitfor - wait for pattern in the input" | |
1468 | .Vb 7 | |
1469 | \& $ok = $obj->waitfor($matchop); | |
1470 | \& $ok = $obj->waitfor([Match => $matchop,] | |
1471 | \& [String => $string,] | |
1472 | \& [Binmode => $mode,] | |
1473 | \& [Errmode => $errmode,] | |
1474 | \& [Telnetmode => $mode,] | |
1475 | \& [Timeout => $secs,]); | |
1476 | .Ve | |
1477 | .Sp | |
1478 | .Vb 7 | |
1479 | \& ($prematch, $match) = $obj->waitfor($matchop); | |
1480 | \& ($prematch, $match) = $obj->waitfor([Match => $matchop,] | |
1481 | \& [String => $string,] | |
1482 | \& [Binmode => $mode,] | |
1483 | \& [Errmode => $errmode,] | |
1484 | \& [Telnetmode => $mode,] | |
1485 | \& [Timeout => $secs,]); | |
1486 | .Ve | |
1487 | .Sp | |
1488 | This method reads until a pattern match or string is found in the | |
1489 | input stream. All the characters before and including the match are | |
1490 | removed from the input stream. | |
1491 | .Sp | |
1492 | In a list context the characters before the match and the matched | |
1493 | characters are returned in \fI$prematch\fR and \fI$match\fR. In a scalar | |
1494 | context, the matched characters and all characters before it are | |
1495 | discarded and \f(CW1\fR is returned on success. On time\-out, eof, or other | |
1496 | failures, for both list and scalar context, the error mode action is | |
1497 | performed. See \f(CW\*(C`errmode()\*(C'\fR. | |
1498 | .Sp | |
1499 | You can specify more than one pattern or string by simply providing | |
1500 | multiple \fIMatch\fR and/or \fIString\fR named parameters. A \fI$matchop\fR | |
1501 | must be a string representing a valid Perl pattern match operator. | |
1502 | The \fI$string\fR is just a substring to find in the input stream. | |
1503 | .Sp | |
1504 | Use \f(CW\*(C`dump_log()\*(C'\fR to debug when this method keeps timing-out and you | |
1505 | don't think it should. | |
1506 | .Sp | |
1507 | An optional named parameter is provided to override the current | |
1508 | setting of timeout. | |
1509 | .Sp | |
1510 | To avoid unexpected backslash interpretation, always use single quotes | |
1511 | instead of double quotes to construct a match operator argument for | |
1512 | \&\f(CW\*(C`prompt()\*(C'\fR and \f(CW\*(C`waitfor()\*(C'\fR (e.g. \f(CW'/bash\e$ $/'\fR). If you're | |
1513 | constructing a \s-1DOS\s0 like file path, you'll need to use four backslashes | |
1514 | to represent one (e.g. \f(CW'/c:\e\e\e\eusers\e\e\e\ebill>$/i'\fR). | |
1515 | .Sp | |
1516 | Of course don't forget about regexp metacharacters like \f(CW\*(C`.\*(C'\fR, \f(CW\*(C`[\*(C'\fR, or | |
1517 | \&\f(CW\*(C`$\*(C'\fR. You'll only need a single backslash to quote them. The anchor | |
1518 | metacharacters \f(CW\*(C`^\*(C'\fR and \f(CW\*(C`$\*(C'\fR refer to positions in the input buffer. | |
1519 | .Sp | |
1520 | Optional named parameters are provided to override the current | |
1521 | settings of binmode, errmode, telnetmode, and timeout. | |
1522 | .SH "SEE ALSO" | |
1523 | .IX Header "SEE ALSO" | |
1524 | .IP "\s-1RFC\s0 854" 2 | |
1525 | .IX Item "RFC 854" | |
1526 | \&\s-1TELNET\s0\ Protocol\ Specification | |
1527 | .Sp | |
1528 | ftp://ftp.isi.edu/in\-notes/rfc854.txt | |
1529 | .IP "\s-1RFC\s0 1143" 2 | |
1530 | .IX Item "RFC 1143" | |
1531 | Q\ Method\ of\ Implementing\ \s-1TELNET\s0\ Option\ Negotiation | |
1532 | .Sp | |
1533 | ftp://ftp.isi.edu/in\-notes/rfc1143.txt | |
1534 | .IP "\s-1TELNET\s0 Option Assignments" 2 | |
1535 | .IX Item "TELNET Option Assignments" | |
1536 | http://www.iana.org/assignments/telnet\-options | |
1537 | .SH "EXAMPLES" | |
1538 | .IX Header "EXAMPLES" | |
1539 | This example gets the current weather forecast for Brainerd, Minnesota. | |
1540 | .PP | |
1541 | .Vb 1 | |
1542 | \& my ($forecast, $t); | |
1543 | .Ve | |
1544 | .PP | |
1545 | .Vb 3 | |
1546 | \& use Net::Telnet (); | |
1547 | \& $t = new Net::Telnet; | |
1548 | \& $t->open("rainmaker.wunderground.com"); | |
1549 | .Ve | |
1550 | .PP | |
1551 | .Vb 3 | |
1552 | \& ## Wait for first prompt and "hit return". | |
1553 | \& $t->waitfor('/continue:.*$/'); | |
1554 | \& $t->print(""); | |
1555 | .Ve | |
1556 | .PP | |
1557 | .Vb 3 | |
1558 | \& ## Wait for second prompt and respond with city code. | |
1559 | \& $t->waitfor('/city code.*$/'); | |
1560 | \& $t->print("BRD"); | |
1561 | .Ve | |
1562 | .PP | |
1563 | .Vb 3 | |
1564 | \& ## Read and print the first page of forecast. | |
1565 | \& ($forecast) = $t->waitfor('/[ \et]+press return to continue/i'); | |
1566 | \& print $forecast; | |
1567 | .Ve | |
1568 | .PP | |
1569 | .Vb 1 | |
1570 | \& exit; | |
1571 | .Ve | |
1572 | .PP | |
1573 | This example checks a \s-1POP\s0 server to see if you have mail. | |
1574 | .PP | |
1575 | .Vb 1 | |
1576 | \& my ($hostname, $line, $passwd, $pop, $username); | |
1577 | .Ve | |
1578 | .PP | |
1579 | .Vb 3 | |
1580 | \& $hostname = "your_destination_host_here"; | |
1581 | \& $username = "your_username_here"; | |
1582 | \& $passwd = "your_password_here"; | |
1583 | .Ve | |
1584 | .PP | |
1585 | .Vb 4 | |
1586 | \& use Net::Telnet (); | |
1587 | \& $pop = new Net::Telnet (Telnetmode => 0); | |
1588 | \& $pop->open(Host => $hostname, | |
1589 | \& Port => 110); | |
1590 | .Ve | |
1591 | .PP | |
1592 | .Vb 3 | |
1593 | \& ## Read connection message. | |
1594 | \& $line = $pop->getline; | |
1595 | \& die $line unless $line =~ /^\e+OK/; | |
1596 | .Ve | |
1597 | .PP | |
1598 | .Vb 4 | |
1599 | \& ## Send user name. | |
1600 | \& $pop->print("user $username"); | |
1601 | \& $line = $pop->getline; | |
1602 | \& die $line unless $line =~ /^\e+OK/; | |
1603 | .Ve | |
1604 | .PP | |
1605 | .Vb 4 | |
1606 | \& ## Send password. | |
1607 | \& $pop->print("pass $passwd"); | |
1608 | \& $line = $pop->getline; | |
1609 | \& die $line unless $line =~ /^\e+OK/; | |
1610 | .Ve | |
1611 | .PP | |
1612 | .Vb 4 | |
1613 | \& ## Request status of messages. | |
1614 | \& $pop->print("list"); | |
1615 | \& $line = $pop->getline; | |
1616 | \& print $line; | |
1617 | .Ve | |
1618 | .PP | |
1619 | .Vb 1 | |
1620 | \& exit; | |
1621 | .Ve | |
1622 | .PP | |
1623 | Here's an example that uses the ssh program to connect to a remote | |
1624 | host. Because the ssh program reads and writes to its controlling | |
1625 | terminal, the IO::Pty module is used to create a new pseudo terminal | |
1626 | for use by ssh. A new Net::Telnet object is then created to read and | |
1627 | write to that pseudo terminal. To use the code below, substitute | |
1628 | \&\*(L"changeme\*(R" with the actual host, user, password, and command prompt. | |
1629 | .PP | |
1630 | .Vb 7 | |
1631 | \& ## Main program. | |
1632 | \& { | |
1633 | \& my ($pty, $ssh, @lines); | |
1634 | \& my $host = "changeme"; | |
1635 | \& my $user = "changeme"; | |
1636 | \& my $password = "changeme"; | |
1637 | \& my $prompt = '/changeme:~> $/'; | |
1638 | .Ve | |
1639 | .PP | |
1640 | .Vb 2 | |
1641 | \& ## Start ssh program. | |
1642 | \& $pty = &spawn("ssh", "-l", $user, $host); # spawn() defined below | |
1643 | .Ve | |
1644 | .PP | |
1645 | .Vb 7 | |
1646 | \& ## Create a Net::Telnet object to perform I/O on ssh's tty. | |
1647 | \& use Net::Telnet; | |
1648 | \& $ssh = new Net::Telnet (-fhopen => $pty, | |
1649 | \& -prompt => $prompt, | |
1650 | \& -telnetmode => 0, | |
1651 | \& -cmd_remove_mode => 1, | |
1652 | \& -output_record_separator => "\er"); | |
1653 | .Ve | |
1654 | .PP | |
1655 | .Vb 8 | |
1656 | \& ## Login to remote host. | |
1657 | \& $ssh->waitfor(-match => '/password: ?$/i', | |
1658 | \& -errmode => "return") | |
1659 | \& or die "problem connecting to host: ", $ssh->lastline; | |
1660 | \& $ssh->print($password); | |
1661 | \& $ssh->waitfor(-match => $ssh->prompt, | |
1662 | \& -errmode => "return") | |
1663 | \& or die "login failed: ", $ssh->lastline; | |
1664 | .Ve | |
1665 | .PP | |
1666 | .Vb 3 | |
1667 | \& ## Send command, get and print its output. | |
1668 | \& @lines = $ssh->cmd("who"); | |
1669 | \& print @lines; | |
1670 | .Ve | |
1671 | .PP | |
1672 | .Vb 2 | |
1673 | \& exit; | |
1674 | \& } # end main program | |
1675 | .Ve | |
1676 | .PP | |
1677 | .Vb 3 | |
1678 | \& sub spawn { | |
1679 | \& my(@cmd) = @_; | |
1680 | \& my($pid, $pty, $tty, $tty_fd); | |
1681 | .Ve | |
1682 | .PP | |
1683 | .Vb 4 | |
1684 | \& ## Create a new pseudo terminal. | |
1685 | \& use IO::Pty (); | |
1686 | \& $pty = new IO::Pty | |
1687 | \& or die $!; | |
1688 | .Ve | |
1689 | .PP | |
1690 | .Vb 3 | |
1691 | \& ## Execute the program in another process. | |
1692 | \& unless ($pid = fork) { # child process | |
1693 | \& die "problem spawning program: $!\en" unless defined $pid; | |
1694 | .Ve | |
1695 | .PP | |
1696 | .Vb 4 | |
1697 | \& ## Disassociate process from existing controlling terminal. | |
1698 | \& use POSIX (); | |
1699 | \& POSIX::setsid | |
1700 | \& or die "setsid failed: $!"; | |
1701 | .Ve | |
1702 | .PP | |
1703 | .Vb 4 | |
1704 | \& ## Associate process with a new controlling terminal. | |
1705 | \& $tty = $pty->slave; | |
1706 | \& $tty_fd = $tty->fileno; | |
1707 | \& close $pty; | |
1708 | .Ve | |
1709 | .PP | |
1710 | .Vb 5 | |
1711 | \& ## Make stdio use the new controlling terminal. | |
1712 | \& open STDIN, "<&$tty_fd" or die $!; | |
1713 | \& open STDOUT, ">&$tty_fd" or die $!; | |
1714 | \& open STDERR, ">&STDOUT" or die $!; | |
1715 | \& close $tty; | |
1716 | .Ve | |
1717 | .PP | |
1718 | .Vb 4 | |
1719 | \& ## Execute requested program. | |
1720 | \& exec @cmd | |
1721 | \& or die "problem executing $cmd[0]\en"; | |
1722 | \& } # end child process | |
1723 | .Ve | |
1724 | .PP | |
1725 | .Vb 2 | |
1726 | \& $pty; | |
1727 | \& } # end sub spawn | |
1728 | .Ve | |
1729 | .PP | |
1730 | Here's an example that changes a user's login password. Because the | |
1731 | passwd program always prompts for passwords on its controlling | |
1732 | terminal, the IO::Pty module is used to create a new pseudo terminal | |
1733 | for use by passwd. A new Net::Telnet object is then created to read | |
1734 | and write to that pseudo terminal. To use the code below, substitute | |
1735 | \&\*(L"changeme\*(R" with the actual old and new passwords. | |
1736 | .PP | |
1737 | .Vb 3 | |
1738 | \& my ($pty, $passwd); | |
1739 | \& my $oldpw = "changeme"; | |
1740 | \& my $newpw = "changeme"; | |
1741 | .Ve | |
1742 | .PP | |
1743 | .Vb 2 | |
1744 | \& ## Start passwd program. | |
1745 | \& $pty = &spawn("passwd"); # spawn() defined above | |
1746 | .Ve | |
1747 | .PP | |
1748 | .Vb 8 | |
1749 | \& ## Create a Net::Telnet object to perform I/O on passwd's tty. | |
1750 | \& use Net::Telnet; | |
1751 | \& $passwd = new Net::Telnet (-fhopen => $pty, | |
1752 | \& -timeout => 2, | |
1753 | \& -output_record_separator => "\er", | |
1754 | \& -telnetmode => 0, | |
1755 | \& -cmd_remove_mode => 1); | |
1756 | \& $passwd->errmode("return"); | |
1757 | .Ve | |
1758 | .PP | |
1759 | .Vb 4 | |
1760 | \& ## Send existing password. | |
1761 | \& $passwd->waitfor('/password: ?$/i') | |
1762 | \& or die "no old password prompt: ", $passwd->lastline; | |
1763 | \& $passwd->print($oldpw); | |
1764 | .Ve | |
1765 | .PP | |
1766 | .Vb 4 | |
1767 | \& ## Send new password. | |
1768 | \& $passwd->waitfor('/new password: ?$/i') | |
1769 | \& or die "bad old password: ", $passwd->lastline; | |
1770 | \& $passwd->print($newpw); | |
1771 | .Ve | |
1772 | .PP | |
1773 | .Vb 4 | |
1774 | \& ## Send new password verification. | |
1775 | \& $passwd->waitfor('/new password: ?$/i') | |
1776 | \& or die "bad new password: ", $passwd->lastline; | |
1777 | \& $passwd->print($newpw); | |
1778 | .Ve | |
1779 | .PP | |
1780 | .Vb 4 | |
1781 | \& ## Display success or failure. | |
1782 | \& $passwd->waitfor('/changed/') | |
1783 | \& or die "bad new password: ", $passwd->lastline; | |
1784 | \& print $passwd->lastline; | |
1785 | .Ve | |
1786 | .PP | |
1787 | .Vb 2 | |
1788 | \& $passwd->close; | |
1789 | \& exit; | |
1790 | .Ve | |
1791 | .PP | |
1792 | Here's an example you can use to down load a file of any type. The | |
1793 | file is read from the remote host's standard output using cat. To | |
1794 | prevent any output processing, the remote host's standard output is | |
1795 | put in raw mode using the Bourne shell. The Bourne shell is used | |
1796 | because some shells, notably tcsh, prevent changing tty modes. Upon | |
1797 | completion, \s-1FTP\s0 style statistics are printed to stderr. | |
1798 | .PP | |
1799 | .Vb 3 | |
1800 | \& my ($block, $filename, $host, $hostname, $k_per_sec, $line, | |
1801 | \& $num_read, $passwd, $prevblock, $prompt, $size, $size_bsd, | |
1802 | \& $size_sysv, $start_time, $total_time, $username); | |
1803 | .Ve | |
1804 | .PP | |
1805 | .Vb 4 | |
1806 | \& $hostname = "your_destination_host_here"; | |
1807 | \& $username = "your_username_here"; | |
1808 | \& $passwd = "your_password_here"; | |
1809 | \& $filename = "your_download_file_here"; | |
1810 | .Ve | |
1811 | .PP | |
1812 | .Vb 6 | |
1813 | \& ## Connect and login. | |
1814 | \& use Net::Telnet (); | |
1815 | \& $host = new Net::Telnet (Timeout => 30, | |
1816 | \& Prompt => '/[%#>] $/'); | |
1817 | \& $host->open($hostname); | |
1818 | \& $host->login($username, $passwd); | |
1819 | .Ve | |
1820 | .PP | |
1821 | .Vb 4 | |
1822 | \& ## Make sure prompt won't match anything in send data. | |
1823 | \& $prompt = "_funkyPrompt_"; | |
1824 | \& $host->prompt("/$prompt\e$/"); | |
1825 | \& $host->cmd("set prompt = '$prompt'"); | |
1826 | .Ve | |
1827 | .PP | |
1828 | .Vb 12 | |
1829 | \& ## Get size of file. | |
1830 | \& ($line) = $host->cmd("/bin/ls -l $filename"); | |
1831 | \& ($size_bsd, $size_sysv) = (split ' ', $line)[3,4]; | |
1832 | \& if ($size_sysv =~ /^\ed+$/) { | |
1833 | \& $size = $size_sysv; | |
1834 | \& } | |
1835 | \& elsif ($size_bsd =~ /^\ed+$/) { | |
1836 | \& $size = $size_bsd; | |
1837 | \& } | |
1838 | \& else { | |
1839 | \& die "$filename: no such file on $hostname"; | |
1840 | \& } | |
1841 | .Ve | |
1842 | .PP | |
1843 | .Vb 5 | |
1844 | \& ## Start sending the file. | |
1845 | \& binmode STDOUT; | |
1846 | \& $host->binmode(1); | |
1847 | \& $host->print("/bin/sh -c 'stty raw; cat $filename'"); | |
1848 | \& $host->getline; # discard echoed back line | |
1849 | .Ve | |
1850 | .PP | |
1851 | .Vb 13 | |
1852 | \& ## Read file a block at a time. | |
1853 | \& $num_read = 0; | |
1854 | \& $prevblock = ""; | |
1855 | \& $start_time = time; | |
1856 | \& while (($block = $host->get) and ($block !~ /$prompt$/o)) { | |
1857 | \& if (length $block >= length $prompt) { | |
1858 | \& print $prevblock; | |
1859 | \& $num_read += length $prevblock; | |
1860 | \& $prevblock = $block; | |
1861 | \& } | |
1862 | \& else { | |
1863 | \& $prevblock .= $block; | |
1864 | \& } | |
1865 | .Ve | |
1866 | .PP | |
1867 | .Vb 2 | |
1868 | \& } | |
1869 | \& $host->close; | |
1870 | .Ve | |
1871 | .PP | |
1872 | .Vb 7 | |
1873 | \& ## Print last block without trailing prompt. | |
1874 | \& $prevblock .= $block; | |
1875 | \& $prevblock =~ s/$prompt$//; | |
1876 | \& print $prevblock; | |
1877 | \& $num_read += length $prevblock; | |
1878 | \& die "error: expected size $size, received size $num_read\en" | |
1879 | \& unless $num_read == $size; | |
1880 | .Ve | |
1881 | .PP | |
1882 | .Vb 6 | |
1883 | \& ## Print totals. | |
1884 | \& $total_time = (time - $start_time) || 1; | |
1885 | \& $k_per_sec = ($size / 1024) / $total_time; | |
1886 | \& $k_per_sec = sprintf "%3.1f", $k_per_sec; | |
1887 | \& warn("$num_read bytes received in $total_time seconds ", | |
1888 | \& "($k_per_sec Kbytes/s)\en"); | |
1889 | .Ve | |
1890 | .PP | |
1891 | .Vb 1 | |
1892 | \& exit; | |
1893 | .Ve | |
1894 | .SH "AUTHOR" | |
1895 | .IX Header "AUTHOR" | |
1896 | Jay Rogers <jay@rgrs.com> | |
1897 | .SH "COPYRIGHT" | |
1898 | .IX Header "COPYRIGHT" | |
1899 | Copyright 1997, 2000, 2002 by Jay Rogers. All rights reserved. | |
1900 | This program is free software; you can redistribute it and/or | |
1901 | modify it under the same terms as Perl itself. |