Debian Codegraph @

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