Debian Codegraph @

upstream/debian-unstable/man3/Net::FTP.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::FTP 3perl"
58 .TH Net::FTP 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::FTP \- FTP Client class
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use Net::FTP;
69 \&
70 \& $ftp = Net::FTP\->new("some.host.name", Debug => 0)
71 \& or die "Cannot connect to some.host.name: $@";
72 \&
73 \& $ftp\->login("anonymous",\*(Aq\-anonymous@\*(Aq)
74 \& or die "Cannot login ", $ftp\->message;
75 \&
76 \& $ftp\->cwd("/pub")
77 \& or die "Cannot change working directory ", $ftp\->message;
78 \&
79 \& $ftp\->get("that.file")
80 \& or die "get failed ", $ftp\->message;
81 \&
82 \& $ftp\->quit;
83 .Ve
84 .SH DESCRIPTION
85 .IX Header "DESCRIPTION"
86 \&\f(CW\*(C`Net::FTP\*(C'\fR is a class implementing a simple FTP client in Perl as
87 described in RFC959. It provides wrappers for the commonly used subset of the
88 RFC959 commands.
89 If IO::Socket::IP or IO::Socket::INET6 is installed it also provides
90 support for IPv6 as defined in RFC2428.
91 And with IO::Socket::SSL installed it provides support for implicit FTPS
92 and explicit FTPS as defined in RFC4217.
93 .PP
94 The Net::FTP class is a subclass of Net::Cmd and (depending on avaibility) of
95 IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
96 .SS Overview
97 .IX Subsection "Overview"
98 FTP stands for File Transfer Protocol. It is a way of transferring
99 files between networked machines. The protocol defines a client
100 (whose commands are provided by this module) and a server (not
101 implemented in this module). Communication is always initiated by the
102 client, and the server responds with a message and a status code (and
103 sometimes with data).
104 .PP
105 The FTP protocol allows files to be sent to or fetched from the
106 server. Each transfer involves a \fBlocal file\fR (on the client) and a
107 \&\fBremote file\fR (on the server). In this module, the same file name
108 will be used for both local and remote if only one is specified. This
109 means that transferring remote file \f(CW\*(C`/path/to/file\*(C'\fR will try to put
110 that file in \f(CW\*(C`/path/to/file\*(C'\fR locally, unless you specify a local file
111 name.
112 .PP
113 The protocol also defines several standard \fBtranslations\fR which the
114 file can undergo during transfer. These are ASCII, EBCDIC, binary,
115 and byte. ASCII is the default type, and indicates that the sender of
116 files will translate the ends of lines to a standard representation
117 which the receiver will then translate back into their local
118 representation. EBCDIC indicates the file being transferred is in
119 EBCDIC format. Binary (also known as image) format sends the data as
120 a contiguous bit stream. Byte format transfers the data as bytes, the
121 values of which remain the same regardless of differences in byte size
122 between the two machines (in theory \- in practice you should only use
123 this if you really know what you're doing). This class does not support
124 the EBCDIC or byte formats, and will default to binary instead if they
125 are attempted.
126 .SS "Class Methods"
127 .IX Subsection "Class Methods"
128 .ie n .IP """new([$host][, %options])""" 4
129 .el .IP "\f(CWnew([$host][, %options])\fR" 4
130 .IX Item "new([$host][, %options])"
131 This is the constructor for a new Net::FTP object. \f(CW$host\fR is the
132 name of the remote host to which an FTP connection is required.
133 .Sp
134 \&\f(CW$host\fR is optional. If \f(CW$host\fR is not given then it may instead be
135 passed as the \f(CW\*(C`Host\*(C'\fR option described below.
136 .Sp
137 \&\f(CW%options\fR are passed in a hash like fashion, using key and value pairs.
138 Possible options are:
139 .Sp
140 \&\fBHost\fR \- FTP host to connect to. It may be a single scalar, as defined for
141 the \f(CW\*(C`PeerAddr\*(C'\fR option in IO::Socket::INET, or a reference to
142 an array with hosts to try in turn. The "host" method will return the value
143 which was used to connect to the host.
144 .Sp
145 \&\fBFirewall\fR \- The name of a machine which acts as an FTP firewall. This can be
146 overridden by an environment variable \f(CW\*(C`FTP_FIREWALL\*(C'\fR. If specified, and the
147 given host cannot be directly connected to, then the
148 connection is made to the firewall machine and the string \f(CW@hostname\fR is
149 appended to the login identifier. This kind of setup is also referred to
150 as an ftp proxy.
151 .Sp
152 \&\fBFirewallType\fR \- The type of firewall running on the machine indicated by
153 \&\fBFirewall\fR. This can be overridden by an environment variable
154 \&\f(CW\*(C`FTP_FIREWALL_TYPE\*(C'\fR. For a list of permissible types, see the description of
155 ftp_firewall_type in Net::Config.
156 .Sp
157 \&\fBBlockSize\fR \- This is the block size that Net::FTP will use when doing
158 transfers. (defaults to 10240)
159 .Sp
160 \&\fBPort\fR \- The port number to connect to on the remote machine for the
161 FTP connection
162 .Sp
163 \&\fBSSL\fR \- If the connection should be done from start with SSL, contrary to later
164 upgrade with \f(CW\*(C`starttls\*(C'\fR.
165 .Sp
166 \&\fBSSL_*\fR \- SSL arguments which will be applied when upgrading the control or
167 data connection to SSL. You can use SSL arguments as documented in
168 IO::Socket::SSL, but it will usually use the right arguments already.
169 .Sp
170 \&\fBTimeout\fR \- Set a timeout value in seconds (defaults to 120)
171 .Sp
172 \&\fBDebug\fR \- debug level (see the debug method in Net::Cmd)
173 .Sp
174 \&\fBPassive\fR \- If set to a non-zero value then all data transfers will
175 be done using passive mode. If set to zero then data transfers will be
176 done using active mode. If the machine is connected to the Internet
177 directly, both passive and active mode should work equally well.
178 Behind most firewall and NAT configurations passive mode has a better
179 chance of working. However, in some rare firewall configurations,
180 active mode actually works when passive mode doesn't. Some really old
181 FTP servers might not implement passive transfers. If not specified,
182 then the transfer mode is set by the environment variable
183 \&\f(CW\*(C`FTP_PASSIVE\*(C'\fR or if that one is not set by the settings done by the
184 \&\fIlibnetcfg\fR utility. If none of these apply then passive mode is
185 used.
186 .Sp
187 \&\fBHash\fR \- If given a reference to a file handle (e.g., \f(CW\*(C`\e*STDERR\*(C'\fR),
188 print hash marks (#) on that filehandle every 1024 bytes. This
189 simply invokes the \f(CWhash()\fR method for you, so that hash marks
190 are displayed for all transfers. You can, of course, call \f(CWhash()\fR
191 explicitly whenever you'd like.
192 .Sp
193 \&\fBLocalAddr\fR \- Local address to use for all socket connections. This
194 argument will be passed to the super class, i.e. IO::Socket::INET
195 or IO::Socket::IP.
196 .Sp
197 \&\fBDomain\fR \- Domain to use, i.e. AF_INET or AF_INET6. This
198 argument will be passed to the IO::Socket super class.
199 This can be used to enforce IPv4 even with IO::Socket::IP
200 which would default to IPv6.
201 \&\fBFamily\fR is accepted as alternative name for \fBDomain\fR.
202 .Sp
203 If the constructor fails undef will be returned and an error message will
204 be in $@
205 .SS "Object Methods"
206 .IX Subsection "Object Methods"
207 Unless otherwise stated all methods return either a \fItrue\fR or \fIfalse\fR
208 value, with \fItrue\fR meaning that the operation was a success. When a method
209 states that it returns a value, failure will be returned as \fIundef\fR or an
210 empty list.
211 .PP
212 \&\f(CW\*(C`Net::FTP\*(C'\fR inherits from \f(CW\*(C`Net::Cmd\*(C'\fR so methods defined in \f(CW\*(C`Net::Cmd\*(C'\fR may
213 be used to send commands to the remote FTP server in addition to the methods
214 documented here.
215 .ie n .IP """login([$login[, $password[, $account]]])""" 4
216 .el .IP "\f(CWlogin([$login[, $password[, $account]]])\fR" 4
217 .IX Item "login([$login[, $password[, $account]]])"
218 Log into the remote FTP server with the given login information. If
219 no arguments are given then the \f(CW\*(C`Net::FTP\*(C'\fR uses the \f(CW\*(C`Net::Netrc\*(C'\fR
220 package to lookup the login information for the connected host.
221 If no information is found then a login of \fIanonymous\fR is used.
222 If no password is given and the login is \fIanonymous\fR then \fIanonymous@\fR
223 will be used for password.
224 .Sp
225 If the connection is via a firewall then the \f(CW\*(C`authorize\*(C'\fR method will
226 be called with no arguments.
227 .ie n .IP starttls() 4
228 .el .IP \f(CWstarttls()\fR 4
229 .IX Item "starttls()"
230 Upgrade existing plain connection to SSL.
231 The SSL arguments have to be given in \f(CW\*(C`new\*(C'\fR already because they are needed for
232 data connections too.
233 .ie n .IP stoptls() 4
234 .el .IP \f(CWstoptls()\fR 4
235 .IX Item "stoptls()"
236 Downgrade existing SSL connection back to plain.
237 This is needed to work with some FTP helpers at firewalls, which need to see the
238 PORT and PASV commands and responses to dynamically open the necessary ports.
239 In this case \f(CW\*(C`starttls\*(C'\fR is usually only done to protect the authorization.
240 .ie n .IP prot($level) 4
241 .el .IP \f(CWprot($level)\fR 4
242 .IX Item "prot($level)"
243 Set what type of data channel protection the client and server will be using.
244 Only \f(CW$level\fRs "C" (clear) and "P" (private) are supported.
245 .ie n .IP host() 4
246 .el .IP \f(CWhost()\fR 4
247 .IX Item "host()"
248 Returns the value used by the constructor, and passed to the IO::Socket super
249 class to connect to the host.
250 .ie n .IP account($acct) 4
251 .el .IP \f(CWaccount($acct)\fR 4
252 .IX Item "account($acct)"
253 Set a string identifying the user's account.
254 .ie n .IP """authorize([$auth[, $resp]])""" 4
255 .el .IP "\f(CWauthorize([$auth[, $resp]])\fR" 4
256 .IX Item "authorize([$auth[, $resp]])"
257 This is a protocol used by some firewall ftp proxies. It is used
258 to authorise the user to send data out. If both arguments are not specified
259 then \f(CW\*(C`authorize\*(C'\fR uses \f(CW\*(C`Net::Netrc\*(C'\fR to do a lookup.
260 .ie n .IP site($args) 4
261 .el .IP \f(CWsite($args)\fR 4
262 .IX Item "site($args)"
263 Send a SITE command to the remote server and wait for a response.
264 .Sp
265 Returns most significant digit of the response code.
266 .ie n .IP ascii() 4
267 .el .IP \f(CWascii()\fR 4
268 .IX Item "ascii()"
269 Transfer file in ASCII. CRLF translation will be done if required
270 .ie n .IP binary() 4
271 .el .IP \f(CWbinary()\fR 4
272 .IX Item "binary()"
273 Transfer file in binary mode. No transformation will be done.
274 .Sp
275 \&\fBHint\fR: If both server and client machines use the same line ending for
276 text files, then it will be faster to transfer all files in binary mode.
277 .ie n .IP type([$type]) 4
278 .el .IP \f(CWtype([$type])\fR 4
279 .IX Item "type([$type])"
280 Set or get if files will be transferred in ASCII or binary mode.
281 .ie n .IP """rename($oldname, $newname)""" 4
282 .el .IP "\f(CWrename($oldname, $newname)\fR" 4
283 .IX Item "rename($oldname, $newname)"
284 Rename a file on the remote FTP server from \f(CW$oldname\fR to \f(CW$newname\fR. This
285 is done by sending the RNFR and RNTO commands.
286 .ie n .IP delete($filename) 4
287 .el .IP \f(CWdelete($filename)\fR 4
288 .IX Item "delete($filename)"
289 Send a request to the server to delete \f(CW$filename\fR.
290 .ie n .IP cwd([$dir]) 4
291 .el .IP \f(CWcwd([$dir])\fR 4
292 .IX Item "cwd([$dir])"
293 Attempt to change directory to the directory given in \f(CW$dir\fR. If
294 \&\f(CW$dir\fR is \f(CW".."\fR, the FTP \f(CW\*(C`CDUP\*(C'\fR command is used to attempt to
295 move up one directory. If no directory is given then an attempt is made
296 to change the directory to the root directory.
297 .ie n .IP cdup() 4
298 .el .IP \f(CWcdup()\fR 4
299 .IX Item "cdup()"
300 Change directory to the parent of the current directory.
301 .ie n .IP passive([$passive]) 4
302 .el .IP \f(CWpassive([$passive])\fR 4
303 .IX Item "passive([$passive])"
304 Set or get if data connections will be initiated in passive mode.
305 .ie n .IP pwd() 4
306 .el .IP \f(CWpwd()\fR 4
307 .IX Item "pwd()"
308 Returns the full pathname of the current directory.
309 .ie n .IP restart($where) 4
310 .el .IP \f(CWrestart($where)\fR 4
311 .IX Item "restart($where)"
312 Set the byte offset at which to begin the next data transfer. Net::FTP simply
313 records this value and uses it when during the next data transfer. For this
314 reason this method will not return an error, but setting it may cause
315 a subsequent data transfer to fail.
316 .ie n .IP """rmdir($dir[, $recurse])""" 4
317 .el .IP "\f(CWrmdir($dir[, $recurse])\fR" 4
318 .IX Item "rmdir($dir[, $recurse])"
319 Remove the directory with the name \f(CW$dir\fR. If \f(CW$recurse\fR is \fItrue\fR then
320 \&\f(CW\*(C`rmdir\*(C'\fR will attempt to delete everything inside the directory.
321 .ie n .IP """mkdir($dir[, $recurse])""" 4
322 .el .IP "\f(CWmkdir($dir[, $recurse])\fR" 4
323 .IX Item "mkdir($dir[, $recurse])"
324 Create a new directory with the name \f(CW$dir\fR. If \f(CW$recurse\fR is \fItrue\fR then
325 \&\f(CW\*(C`mkdir\*(C'\fR will attempt to create all the directories in the given path.
326 .Sp
327 Returns the full pathname to the new directory.
328 .ie n .IP """alloc($size[, $record_size])""" 4
329 .el .IP "\f(CWalloc($size[, $record_size])\fR" 4
330 .IX Item "alloc($size[, $record_size])"
331 The alloc command allows you to give the ftp server a hint about the size
332 of the file about to be transferred using the ALLO ftp command. Some storage
333 systems use this to make intelligent decisions about how to store the file.
334 The \f(CW$size\fR argument represents the size of the file in bytes. The
335 \&\f(CW$record_size\fR argument indicates a maximum record or page size for files
336 sent with a record or page structure.
337 .Sp
338 The size of the file will be determined, and sent to the server
339 automatically for normal files so that this method need only be called if
340 you are transferring data from a socket, named pipe, or other stream not
341 associated with a normal file.
342 .ie n .IP ls([$dir]) 4
343 .el .IP \f(CWls([$dir])\fR 4
344 .IX Item "ls([$dir])"
345 Get a directory listing of \f(CW$dir\fR, or the current directory.
346 .Sp
347 In an array context, returns a list of lines returned from the server. In
348 a scalar context, returns a reference to a list.
349 .ie n .IP dir([$dir]) 4
350 .el .IP \f(CWdir([$dir])\fR 4
351 .IX Item "dir([$dir])"
352 Get a directory listing of \f(CW$dir\fR, or the current directory in long format.
353 .Sp
354 In an array context, returns a list of lines returned from the server. In
355 a scalar context, returns a reference to a list.
356 .ie n .IP """get($remote_file[, $local_file[, $where]])""" 4
357 .el .IP "\f(CWget($remote_file[, $local_file[, $where]])\fR" 4
358 .IX Item "get($remote_file[, $local_file[, $where]])"
359 Get \f(CW$remote_file\fR from the server and store locally. \f(CW$local_file\fR may be
360 a filename or a filehandle. If not specified, the file will be stored in
361 the current directory with the same leafname as the remote file.
362 .Sp
363 If \f(CW$where\fR is given then the first \f(CW$where\fR bytes of the file will
364 not be transferred, and the remaining bytes will be appended to
365 the local file if it already exists.
366 .Sp
367 Returns \f(CW$local_file\fR, or the generated local file name if \f(CW$local_file\fR
368 is not given. If an error was encountered undef is returned.
369 .ie n .IP """put($local_file[, $remote_file])""" 4
370 .el .IP "\f(CWput($local_file[, $remote_file])\fR" 4
371 .IX Item "put($local_file[, $remote_file])"
372 Put a file on the remote server. \f(CW$local_file\fR may be a name or a filehandle.
373 If \f(CW$local_file\fR is a filehandle then \f(CW$remote_file\fR must be specified. If
374 \&\f(CW$remote_file\fR is not specified then the file will be stored in the current
375 directory with the same leafname as \f(CW$local_file\fR.
376 .Sp
377 Returns \f(CW$remote_file\fR, or the generated remote filename if \f(CW$remote_file\fR
378 is not given.
379 .Sp
380 \&\fBNOTE\fR: If for some reason the transfer does not complete and an error is
381 returned then the contents that had been transferred will not be remove
382 automatically.
383 .ie n .IP """put_unique($local_file[, $remote_file])""" 4
384 .el .IP "\f(CWput_unique($local_file[, $remote_file])\fR" 4
385 .IX Item "put_unique($local_file[, $remote_file])"
386 Same as put but uses the \f(CW\*(C`STOU\*(C'\fR command.
387 .Sp
388 Returns the name of the file on the server.
389 .ie n .IP """append($local_file[, $remote_file])""" 4
390 .el .IP "\f(CWappend($local_file[, $remote_file])\fR" 4
391 .IX Item "append($local_file[, $remote_file])"
392 Same as put but appends to the file on the remote server.
393 .Sp
394 Returns \f(CW$remote_file\fR, or the generated remote filename if \f(CW$remote_file\fR
395 is not given.
396 .ie n .IP unique_name() 4
397 .el .IP \f(CWunique_name()\fR 4
398 .IX Item "unique_name()"
399 Returns the name of the last file stored on the server using the
400 \&\f(CW\*(C`STOU\*(C'\fR command.
401 .ie n .IP mdtm($file) 4
402 .el .IP \f(CWmdtm($file)\fR 4
403 .IX Item "mdtm($file)"
404 Returns the \fImodification time\fR of the given file
405 .ie n .IP size($file) 4
406 .el .IP \f(CWsize($file)\fR 4
407 .IX Item "size($file)"
408 Returns the size in bytes for the given file as stored on the remote server.
409 .Sp
410 \&\fBNOTE\fR: The size reported is the size of the stored file on the remote server.
411 If the file is subsequently transferred from the server in ASCII mode
412 and the remote server and local machine have different ideas about
413 "End Of Line" then the size of file on the local machine after transfer
414 may be different.
415 .ie n .IP supported($cmd) 4
416 .el .IP \f(CWsupported($cmd)\fR 4
417 .IX Item "supported($cmd)"
418 Returns TRUE if the remote server supports the given command.
419 .ie n .IP """hash([$filehandle_glob_ref[, $bytes_per_hash_mark]])""" 4
420 .el .IP "\f(CWhash([$filehandle_glob_ref[, $bytes_per_hash_mark]])\fR" 4
421 .IX Item "hash([$filehandle_glob_ref[, $bytes_per_hash_mark]])"
422 Called without parameters, or with the first argument false, hash marks
423 are suppressed. If the first argument is true but not a reference to a
424 file handle glob, then \e*STDERR is used. The second argument is the number
425 of bytes per hash mark printed, and defaults to 1024. In all cases the
426 return value is a reference to an array of two: the filehandle glob reference
427 and the bytes per hash mark.
428 .ie n .IP feature($name) 4
429 .el .IP \f(CWfeature($name)\fR 4
430 .IX Item "feature($name)"
431 Determine if the server supports the specified feature. The return
432 value is a list of lines the server responded with to describe the
433 options that it supports for the given feature. If the feature is
434 unsupported then the empty list is returned.
435 .Sp
436 .Vb 3
437 \& if ($ftp\->feature( \*(AqMDTM\*(Aq )) {
438 \& # Do something
439 \& }
440 \&
441 \& if (grep { /\ebTLS\eb/ } $ftp\->feature(\*(AqAUTH\*(Aq)) {
442 \& # Server supports TLS
443 \& }
444 .Ve
445 .PP
446 The following methods can return different results depending on
447 how they are called. If the user explicitly calls either
448 of the \f(CW\*(C`pasv\*(C'\fR or \f(CW\*(C`port\*(C'\fR methods then these methods will
449 return a \fItrue\fR or \fIfalse\fR value. If the user does not
450 call either of these methods then the result will be a
451 reference to a \f(CW\*(C`Net::FTP::dataconn\*(C'\fR based object.
452 .ie n .IP nlst([$dir]) 4
453 .el .IP \f(CWnlst([$dir])\fR 4
454 .IX Item "nlst([$dir])"
455 Send an \f(CW\*(C`NLST\*(C'\fR command to the server, with an optional parameter.
456 .ie n .IP list([$dir]) 4
457 .el .IP \f(CWlist([$dir])\fR 4
458 .IX Item "list([$dir])"
459 Same as \f(CW\*(C`nlst\*(C'\fR but using the \f(CW\*(C`LIST\*(C'\fR command
460 .ie n .IP retr($file) 4
461 .el .IP \f(CWretr($file)\fR 4
462 .IX Item "retr($file)"
463 Begin the retrieval of a file called \f(CW$file\fR from the remote server.
464 .ie n .IP stor($file) 4
465 .el .IP \f(CWstor($file)\fR 4
466 .IX Item "stor($file)"
467 Tell the server that you wish to store a file. \f(CW$file\fR is the
468 name of the new file that should be created.
469 .ie n .IP stou($file) 4
470 .el .IP \f(CWstou($file)\fR 4
471 .IX Item "stou($file)"
472 Same as \f(CW\*(C`stor\*(C'\fR but using the \f(CW\*(C`STOU\*(C'\fR command. The name of the unique
473 file which was created on the server will be available via the \f(CW\*(C`unique_name\*(C'\fR
474 method after the data connection has been closed.
475 .ie n .IP appe($file) 4
476 .el .IP \f(CWappe($file)\fR 4
477 .IX Item "appe($file)"
478 Tell the server that we want to append some data to the end of a file
479 called \f(CW$file\fR. If this file does not exist then create it.
480 .PP
481 If for some reason you want to have complete control over the data connection,
482 this includes generating it and calling the \f(CW\*(C`response\*(C'\fR method when required,
483 then the user can use these methods to do so.
484 .PP
485 However calling these methods only affects the use of the methods above that
486 can return a data connection. They have no effect on methods \f(CW\*(C`get\*(C'\fR, \f(CW\*(C`put\*(C'\fR,
487 \&\f(CW\*(C`put_unique\*(C'\fR and those that do not require data connections.
488 .ie n .IP port([$port]) 4
489 .el .IP \f(CWport([$port])\fR 4
490 .IX Item "port([$port])"
491 .PD 0
492 .ie n .IP eprt([$port]) 4
493 .el .IP \f(CWeprt([$port])\fR 4
494 .IX Item "eprt([$port])"
495 .PD
496 Send a \f(CW\*(C`PORT\*(C'\fR (IPv4) or \f(CW\*(C`EPRT\*(C'\fR (IPv6) command to the server. If \f(CW$port\fR is
497 specified then it is sent to the server. If not, then a listen socket is created
498 and the correct information sent to the server.
499 .ie n .IP pasv() 4
500 .el .IP \f(CWpasv()\fR 4
501 .IX Item "pasv()"
502 .PD 0
503 .ie n .IP epsv() 4
504 .el .IP \f(CWepsv()\fR 4
505 .IX Item "epsv()"
506 .PD
507 Tell the server to go into passive mode (\f(CW\*(C`pasv\*(C'\fR for IPv4, \f(CW\*(C`epsv\*(C'\fR for IPv6).
508 Returns the text that represents the port on which the server is listening, this
509 text is in a suitable form to send to another ftp server using the \f(CW\*(C`port\*(C'\fR or
510 \&\f(CW\*(C`eprt\*(C'\fR method.
511 .PP
512 The following methods can be used to transfer files between two remote
513 servers, providing that these two servers can connect directly to each other.
514 .ie n .IP """pasv_xfer($src_file, $dest_server[, $dest_file ])""" 4
515 .el .IP "\f(CWpasv_xfer($src_file, $dest_server[, $dest_file ])\fR" 4
516 .IX Item "pasv_xfer($src_file, $dest_server[, $dest_file ])"
517 This method will do a file transfer between two remote ftp servers. If
518 \&\f(CW$dest_file\fR is omitted then the leaf name of \f(CW$src_file\fR will be used.
519 .ie n .IP """pasv_xfer_unique($src_file, $dest_server[, $dest_file ])""" 4
520 .el .IP "\f(CWpasv_xfer_unique($src_file, $dest_server[, $dest_file ])\fR" 4
521 .IX Item "pasv_xfer_unique($src_file, $dest_server[, $dest_file ])"
522 Like \f(CW\*(C`pasv_xfer\*(C'\fR but the file is stored on the remote server using
523 the STOU command.
524 .ie n .IP pasv_wait($non_pasv_server) 4
525 .el .IP \f(CWpasv_wait($non_pasv_server)\fR 4
526 .IX Item "pasv_wait($non_pasv_server)"
527 This method can be used to wait for a transfer to complete between a passive
528 server and a non-passive server. The method should be called on the passive
529 server with the \f(CW\*(C`Net::FTP\*(C'\fR object for the non-passive server passed as an
530 argument.
531 .ie n .IP abort() 4
532 .el .IP \f(CWabort()\fR 4
533 .IX Item "abort()"
534 Abort the current data transfer.
535 .ie n .IP quit() 4
536 .el .IP \f(CWquit()\fR 4
537 .IX Item "quit()"
538 Send the QUIT command to the remote FTP server and close the socket connection.
539 .SS "Methods for the Adventurous"
540 .IX Subsection "Methods for the Adventurous"
541 .ie n .IP """quot($cmd[, $args])""" 4
542 .el .IP "\f(CWquot($cmd[, $args])\fR" 4
543 .IX Item "quot($cmd[, $args])"
544 Send a command, that Net::FTP does not directly support, to the remote
545 server and wait for a response.
546 .Sp
547 Returns most significant digit of the response code.
548 .Sp
549 \&\fBWARNING\fR This call should only be used on commands that do not require
550 data connections. Misuse of this method can hang the connection.
551 .ie n .IP can_inet6() 4
552 .el .IP \f(CWcan_inet6()\fR 4
553 .IX Item "can_inet6()"
554 Returns whether we can use IPv6.
555 .ie n .IP can_ssl() 4
556 .el .IP \f(CWcan_ssl()\fR 4
557 .IX Item "can_ssl()"
558 Returns whether we can use SSL.
559 .SS "The dataconn Class"
560 .IX Subsection "The dataconn Class"
561 Some of the methods defined in \f(CW\*(C`Net::FTP\*(C'\fR return an object which will
562 be derived from the \f(CW\*(C`Net::FTP::dataconn\*(C'\fR class. See Net::FTP::dataconn for
563 more details.
564 .SS Unimplemented
565 .IX Subsection "Unimplemented"
566 The following RFC959 commands have not been implemented:
567 .ie n .IP """SMNT""" 4
568 .el .IP \f(CWSMNT\fR 4
569 .IX Item "SMNT"
570 Mount a different file system structure without changing login or
571 accounting information.
572 .ie n .IP """HELP""" 4
573 .el .IP \f(CWHELP\fR 4
574 .IX Item "HELP"
575 Ask the server for "helpful information" (that's what the RFC says) on
576 the commands it accepts.
577 .ie n .IP """MODE""" 4
578 .el .IP \f(CWMODE\fR 4
579 .IX Item "MODE"
580 Specifies transfer mode (stream, block or compressed) for file to be
581 transferred.
582 .ie n .IP """SYST""" 4
583 .el .IP \f(CWSYST\fR 4
584 .IX Item "SYST"
585 Request remote server system identification.
586 .ie n .IP """STAT""" 4
587 .el .IP \f(CWSTAT\fR 4
588 .IX Item "STAT"
589 Request remote server status.
590 .ie n .IP """STRU""" 4
591 .el .IP \f(CWSTRU\fR 4
592 .IX Item "STRU"
593 Specifies file structure for file to be transferred.
594 .ie n .IP """REIN""" 4
595 .el .IP \f(CWREIN\fR 4
596 .IX Item "REIN"
597 Reinitialize the connection, flushing all I/O and account information.
598 .SH EXPORTS
599 .IX Header "EXPORTS"
600 \&\fINone\fR.
601 .SH "KNOWN BUGS"
602 .IX Header "KNOWN BUGS"
603 See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
604 .SS "Reporting Bugs"
605 .IX Subsection "Reporting Bugs"
606 When reporting bugs/problems please include as much information as possible.
607 It may be difficult for me to reproduce the problem as almost every setup
608 is different.
609 .PP
610 A small script which yields the problem will probably be of help. It would
611 also be useful if this script was run with the extra options \f(CW\*(C`Debug => 1\*(C'\fR
612 passed to the constructor, and the output sent with the bug report. If you
613 cannot include a small script then please include a Debug trace from a
614 run of your program which does yield the problem.
615 .SH "SEE ALSO"
616 .IX Header "SEE ALSO"
617 Net::Netrc,
618 Net::Cmd,
619 IO::Socket::SSL;
620 .PP
621 \&\fBftp\fR\|(1),
622 \&\fBftpd\fR\|(8);
623 .PP
624 <https://www.ietf.org/rfc/rfc959.txt>,
625 <https://www.ietf.org/rfc/rfc2428.txt>,
626 <https://www.ietf.org/rfc/rfc4217.txt>.
627 .SH ACKNOWLEDGEMENTS
628 .IX Header "ACKNOWLEDGEMENTS"
629 Henry Gabryjelski <[email protected] <mailto:[email protected]>> \- for the
630 suggestion of creating directories recursively.
631 .PP
632 Nathan Torkington <[email protected] <mailto:[email protected]>> \- for some
633 input on the documentation.
634 .PP
635 Roderick Schertler <[email protected] <mailto:[email protected]>> \- for
636 various inputs
637 .SH AUTHOR
638 .IX Header "AUTHOR"
639 Graham Barr <[email protected] <mailto:[email protected]>>.
640 .PP
641 Steve Hay <[email protected] <mailto:[email protected]>> is now maintaining
642 libnet as of version 1.22_02.
643 .SH COPYRIGHT
644 .IX Header "COPYRIGHT"
645 Copyright (C) 1995\-2004 Graham Barr. All rights reserved.
646 .PP
647 Copyright (C) 2013\-2017, 2020, 2022 Steve Hay. All rights reserved.
648 .SH LICENCE
649 .IX Header "LICENCE"
650 This module is free software; you can redistribute it and/or modify it under the
651 same terms as Perl itself, i.e. under the terms of either the GNU General Public
652 License or the Artistic License, as specified in the \fILICENCE\fR file.
653 .SH VERSION
654 .IX Header "VERSION"
655 Version 3.15
656 .SH DATE
657 .IX Header "DATE"
658 20 March 2023
659 .SH HISTORY
660 .IX Header "HISTORY"
661 See the \fIChanges\fR file.