Debian Codegraph @

upstream/debian-unstable/man3/Net::Cmd.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Net::Cmd 3perl"
58 .TH Net::Cmd 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Net::Cmd \- Network Command class (as used by FTP, SMTP etc)
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use Net::Cmd;
69 \&
70 \& @ISA = qw(Net::Cmd);
71 .Ve
72 .SH DESCRIPTION
73 .IX Header "DESCRIPTION"
74 \&\f(CW\*(C`Net::Cmd\*(C'\fR is a collection of methods that can be inherited by a sub-class
75 of \f(CW\*(C`IO::Socket::INET\*(C'\fR. These methods implement the functionality required for a
76 command based protocol, for example FTP and SMTP.
77 .PP
78 If your sub-class does not also derive from \f(CW\*(C`IO::Socket::INET\*(C'\fR or similar (e.g.
79 \&\f(CW\*(C`IO::Socket::IP\*(C'\fR, \f(CW\*(C`IO::Socket::INET6\*(C'\fR or \f(CW\*(C`IO::Socket::SSL\*(C'\fR) then you must
80 provide the following methods by other means yourself: \f(CWclose()\fR and
81 \&\f(CWtimeout()\fR.
82 .SS "Public Methods"
83 .IX Subsection "Public Methods"
84 These methods provide a user interface to the \f(CW\*(C`Net::Cmd\*(C'\fR object.
85 .ie n .IP debug($level) 4
86 .el .IP \f(CWdebug($level)\fR 4
87 .IX Item "debug($level)"
88 Set the level of debug information for this object. If \f(CW$level\fR is not given
89 then the current state is returned. Otherwise the state is changed to
90 \&\f(CW$level\fR and the previous state returned.
91 .Sp
92 Different packages
93 may implement different levels of debug but a non-zero value results in
94 copies of all commands and responses also being sent to STDERR.
95 .Sp
96 If \f(CW$level\fR is \f(CW\*(C`undef\*(C'\fR then the debug level will be set to the default
97 debug level for the class.
98 .Sp
99 This method can also be called as a \fIstatic\fR method to set/get the default
100 debug level for a given class.
101 .ie n .IP message() 4
102 .el .IP \f(CWmessage()\fR 4
103 .IX Item "message()"
104 Returns the text message returned from the last command. In a scalar
105 context it returns a single string, in a list context it will return
106 each line as a separate element. (See "PSEUDO RESPONSES" below.)
107 .ie n .IP code() 4
108 .el .IP \f(CWcode()\fR 4
109 .IX Item "code()"
110 Returns the 3\-digit code from the last command. If a command is pending
111 then the value 0 is returned. (See "PSEUDO RESPONSES" below.)
112 .ie n .IP ok() 4
113 .el .IP \f(CWok()\fR 4
114 .IX Item "ok()"
115 Returns non-zero if the last code value was greater than zero and
116 less than 400. This holds true for most command servers. Servers
117 where this does not hold may override this method.
118 .ie n .IP status() 4
119 .el .IP \f(CWstatus()\fR 4
120 .IX Item "status()"
121 Returns the most significant digit of the current status code. If a command
122 is pending then \f(CW\*(C`CMD_PENDING\*(C'\fR is returned.
123 .ie n .IP datasend($data) 4
124 .el .IP \f(CWdatasend($data)\fR 4
125 .IX Item "datasend($data)"
126 Send data to the remote server, converting LF to CRLF. Any line starting
127 with a '.' will be prefixed with another '.'.
128 \&\f(CW$data\fR may be an array or a reference to an array.
129 The \f(CW$data\fR passed in must be encoded by the caller to octets of whatever
130 encoding is required, e.g. by using the Encode module's \f(CWencode()\fR function.
131 .ie n .IP dataend() 4
132 .el .IP \f(CWdataend()\fR 4
133 .IX Item "dataend()"
134 End the sending of data to the remote server. This is done by ensuring that
135 the data already sent ends with CRLF then sending '.CRLF' to end the
136 transmission. Once this data has been sent \f(CW\*(C`dataend\*(C'\fR calls \f(CW\*(C`response\*(C'\fR and
137 returns true if \f(CW\*(C`response\*(C'\fR returns CMD_OK.
138 .SS "Protected Methods"
139 .IX Subsection "Protected Methods"
140 These methods are not intended to be called by the user, but used or
141 over-ridden by a sub-class of \f(CW\*(C`Net::Cmd\*(C'\fR
142 .ie n .IP """debug_print($dir, $text)""" 4
143 .el .IP "\f(CWdebug_print($dir, $text)\fR" 4
144 .IX Item "debug_print($dir, $text)"
145 Print debugging information. \f(CW$dir\fR denotes the direction \fItrue\fR being
146 data being sent to the server. Calls \f(CW\*(C`debug_text\*(C'\fR before printing to
147 STDERR.
148 .ie n .IP """debug_text($dir, $text)""" 4
149 .el .IP "\f(CWdebug_text($dir, $text)\fR" 4
150 .IX Item "debug_text($dir, $text)"
151 This method is called to print debugging information. \f(CW$text\fR is
152 the text being sent. The method should return the text to be printed.
153 .Sp
154 This is primarily meant for the use of modules such as FTP where passwords
155 are sent, but we do not want to display them in the debugging information.
156 .ie n .IP """command($cmd[, $args, ... ])""" 4
157 .el .IP "\f(CWcommand($cmd[, $args, ... ])\fR" 4
158 .IX Item "command($cmd[, $args, ... ])"
159 Send a command to the command server. All arguments are first joined with
160 a space character and CRLF is appended, this string is then sent to the
161 command server.
162 .Sp
163 Returns undef upon failure.
164 .ie n .IP unsupported() 4
165 .el .IP \f(CWunsupported()\fR 4
166 .IX Item "unsupported()"
167 Sets the status code to 580 and the response text to 'Unsupported command'.
168 Returns zero.
169 .ie n .IP response() 4
170 .el .IP \f(CWresponse()\fR 4
171 .IX Item "response()"
172 Obtain a response from the server. Upon success the most significant digit
173 of the status code is returned. Upon failure, timeout etc., \fICMD_ERROR\fR is
174 returned.
175 .ie n .IP parse_response($text) 4
176 .el .IP \f(CWparse_response($text)\fR 4
177 .IX Item "parse_response($text)"
178 This method is called by \f(CW\*(C`response\*(C'\fR as a method with one argument. It should
179 return an array of 2 values, the 3\-digit status code and a flag which is true
180 when this is part of a multi-line response and this line is not the last.
181 .ie n .IP getline() 4
182 .el .IP \f(CWgetline()\fR 4
183 .IX Item "getline()"
184 Retrieve one line, delimited by CRLF, from the remote server. Returns \fIundef\fR
185 upon failure.
186 .Sp
187 \&\fBNOTE\fR: If you do use this method for any reason, please remember to add
188 some \f(CW\*(C`debug_print\*(C'\fR calls into your method.
189 .ie n .IP ungetline($text) 4
190 .el .IP \f(CWungetline($text)\fR 4
191 .IX Item "ungetline($text)"
192 Unget a line of text from the server.
193 .ie n .IP rawdatasend($data) 4
194 .el .IP \f(CWrawdatasend($data)\fR 4
195 .IX Item "rawdatasend($data)"
196 Send data to the remote server without performing any conversions. \f(CW$data\fR
197 is a scalar.
198 As with \f(CWdatasend()\fR, the \f(CW$data\fR passed in must be encoded by the caller
199 to octets of whatever encoding is required, e.g. by using the Encode module's
200 \&\f(CWencode()\fR function.
201 .ie n .IP read_until_dot() 4
202 .el .IP \f(CWread_until_dot()\fR 4
203 .IX Item "read_until_dot()"
204 Read data from the remote server until a line consisting of a single '.'.
205 Any lines starting with '..' will have one of the '.'s removed.
206 .Sp
207 Returns a reference to a list containing the lines, or \fIundef\fR upon failure.
208 .ie n .IP tied_fh() 4
209 .el .IP \f(CWtied_fh()\fR 4
210 .IX Item "tied_fh()"
211 Returns a filehandle tied to the Net::Cmd object. After issuing a
212 command, you may read from this filehandle using \fBread()\fR or <>. The
213 filehandle will return EOF when the final dot is encountered.
214 Similarly, you may write to the filehandle in order to send data to
215 the server after issuing a command that expects data to be written.
216 .Sp
217 See the Net::POP3 and Net::SMTP modules for examples of this.
218 .SS "Pseudo Responses"
219 .IX Subsection "Pseudo Responses"
220 Normally the values returned by \f(CWmessage()\fR and \f(CWcode()\fR are
221 obtained from the remote server, but in a few circumstances, as
222 detailed below, \f(CW\*(C`Net::Cmd\*(C'\fR will return values that it sets. You
223 can alter this behavior by overriding \fBDEF_REPLY_CODE()\fR to specify
224 a different default reply code, or overriding one of the specific
225 error handling methods below.
226 .IP "Initial value" 4
227 .IX Item "Initial value"
228 Before any command has executed or if an unexpected error occurs
229 \&\f(CWcode()\fR will return "421" (temporary connection failure) and
230 \&\f(CWmessage()\fR will return undef.
231 .IP "Connection closed" 4
232 .IX Item "Connection closed"
233 If the underlying \f(CW\*(C`IO::Handle\*(C'\fR is closed, or if there are
234 any read or write failures, the file handle will be forced closed,
235 and \f(CWcode()\fR will return "421" (temporary connection failure)
236 and \f(CWmessage()\fR will return "[$pkg] Connection closed"
237 (where \f(CW$pkg\fR is the name of the class that subclassed \f(CW\*(C`Net::Cmd\*(C'\fR).
238 The \fB_set_status_closed()\fR method can be overridden to set a different
239 message (by calling \fBset_status()\fR) or otherwise trap this error.
240 .IP Timeout 4
241 .IX Item "Timeout"
242 If there is a read or write timeout \f(CWcode()\fR will return "421"
243 (temporary connection failure) and \f(CWmessage()\fR will return
244 "[$pkg] Timeout" (where \f(CW$pkg\fR is the name of the class
245 that subclassed \f(CW\*(C`Net::Cmd\*(C'\fR). The \fB_set_status_timeout()\fR method
246 can be overridden to set a different message (by calling \fBset_status()\fR)
247 or otherwise trap this error.
248 .SH EXPORTS
249 .IX Header "EXPORTS"
250 The following symbols are, or can be, exported by this module:
251 .IP "Default Exports" 4
252 .IX Item "Default Exports"
253 \&\f(CW\*(C`CMD_INFO\*(C'\fR,
254 \&\f(CW\*(C`CMD_OK\*(C'\fR,
255 \&\f(CW\*(C`CMD_MORE\*(C'\fR,
256 \&\f(CW\*(C`CMD_REJECT\*(C'\fR,
257 \&\f(CW\*(C`CMD_ERROR\*(C'\fR,
258 \&\f(CW\*(C`CMD_PENDING\*(C'\fR.
259 .Sp
260 (These correspond to possible results of \f(CWresponse()\fR and \f(CWstatus()\fR.)
261 .IP "Optional Exports" 4
262 .IX Item "Optional Exports"
263 \&\fINone\fR.
264 .IP "Export Tags" 4
265 .IX Item "Export Tags"
266 \&\fINone\fR.
267 .SH "KNOWN BUGS"
268 .IX Header "KNOWN BUGS"
269 See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
270 .SH AUTHOR
271 .IX Header "AUTHOR"
272 Graham Barr <[email protected] <mailto:[email protected]>>.
273 .PP
274 Steve Hay <[email protected] <mailto:[email protected]>> is now maintaining
275 libnet as of version 1.22_02.
276 .SH COPYRIGHT
277 .IX Header "COPYRIGHT"
278 Copyright (C) 1995\-2006 Graham Barr. All rights reserved.
279 .PP
280 Copyright (C) 2013\-2016, 2020, 2022 Steve Hay. All rights reserved.
281 .SH LICENCE
282 .IX Header "LICENCE"
283 This module is free software; you can redistribute it and/or modify it under the
284 same terms as Perl itself, i.e. under the terms of either the GNU General Public
285 License or the Artistic License, as specified in the \fILICENCE\fR file.
286 .SH VERSION
287 .IX Header "VERSION"
288 Version 3.15
289 .SH DATE
290 .IX Header "DATE"
291 20 March 2023
292 .SH HISTORY
293 .IX Header "HISTORY"
294 See the \fIChanges\fR file.