Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Net::Cmd.3pm

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