1Net::FTP(3) User Contributed Perl Documentation Net::FTP(3)
2
6 Net::FTP - FTP Client class
7
9 use Net::FTP;
10 $ftp = Net::FTP->new("some.host.name", Debug => 0)
12 or die "Cannot connect to some.host.name: $@";
13 $ftp->login("anonymous",'-anonymous@')
15 or die "Cannot login ", $ftp->message;
16 $ftp->cwd("/pub")
18 or die "Cannot change working directory ", $ftp->message;
19 $ftp->get("that.file")
21 or die "get failed ", $ftp->message;
22 $ftp->quit;
24
26 "Net::FTP" is a class implementing a simple FTP client in Perl as
27 described in RFC959. It provides wrappers for the commonly used subset
28 of the RFC959 commands. If IO::Socket::IP or IO::Socket::INET6 is
29 installed it also provides support for IPv6 as defined in RFC2428. And
30 with IO::Socket::SSL installed it provides support for implicit FTPS
31 and explicit FTPS as defined in RFC4217.
32 The Net::FTP class is a subclass of Net::Cmd and (depending on
34 avaibility) of IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
35 Overview
37 FTP stands for File Transfer Protocol. It is a way of transferring
38 files between networked machines. The protocol defines a client (whose
39 commands are provided by this module) and a server (not implemented in
40 this module). Communication is always initiated by the client, and the
41 server responds with a message and a status code (and sometimes with
42 data).
43 The FTP protocol allows files to be sent to or fetched from the server.
45 Each transfer involves a local file (on the client) and a remote file
46 (on the server). In this module, the same file name will be used for
47 both local and remote if only one is specified. This means that
48 transferring remote file "/path/to/file" will try to put that file in
49 "/path/to/file" locally, unless you specify a local file name.
50 The protocol also defines several standard translations which the file
52 can undergo during transfer. These are ASCII, EBCDIC, binary, and
53 byte. ASCII is the default type, and indicates that the sender of
54 files will translate the ends of lines to a standard representation
55 which the receiver will then translate back into their local
56 representation. EBCDIC indicates the file being transferred is in
57 EBCDIC format. Binary (also known as image) format sends the data as a
58 contiguous bit stream. Byte format transfers the data as bytes, the
59 values of which remain the same regardless of differences in byte size
60 between the two machines (in theory - in practice you should only use
61 this if you really know what you're doing). This class does not
62 support the EBCDIC or byte formats, and will default to binary instead
63 if they are attempted.
64 Class Methods
66 "new([$host][, %options])"
67 This is the constructor for a new Net::FTP object. $host is the
68 name of the remote host to which an FTP connection is required.
69 $host is optional. If $host is not given then it may instead be
71 passed as the "Host" option described below.
72 %options are passed in a hash like fashion, using key and value
74 pairs. Possible options are:
75 Host - FTP host to connect to. It may be a single scalar, as
77 defined for the "PeerAddr" option in IO::Socket::INET, or a
78 reference to an array with hosts to try in turn. The "host" method
79 will return the value which was used to connect to the host.
80 Firewall - The name of a machine which acts as an FTP firewall.
82 This can be overridden by an environment variable "FTP_FIREWALL".
83 If specified, and the given host cannot be directly connected to,
84 then the connection is made to the firewall machine and the string
85 @hostname is appended to the login identifier. This kind of setup
86 is also referred to as an ftp proxy.
87 FirewallType - The type of firewall running on the machine
89 indicated by Firewall. This can be overridden by an environment
90 variable "FTP_FIREWALL_TYPE". For a list of permissible types, see
91 the description of ftp_firewall_type in Net::Config.
92 BlockSize - This is the block size that Net::FTP will use when
94 doing transfers. (defaults to 10240)
95 Port - The port number to connect to on the remote machine for the
97 FTP connection
98 SSL - If the connection should be done from start with SSL,
100 contrary to later upgrade with "starttls".
101 SSL_* - SSL arguments which will be applied when upgrading the
103 control or data connection to SSL. You can use SSL arguments as
104 documented in IO::Socket::SSL, but it will usually use the right
105 arguments already.
106 Timeout - Set a timeout value in seconds (defaults to 120)
108 Debug - debug level (see the debug method in Net::Cmd)
110 Passive - If set to a non-zero value then all data transfers will
112 be done using passive mode. If set to zero then data transfers will
113 be done using active mode. If the machine is connected to the
114 Internet directly, both passive and active mode should work equally
115 well. Behind most firewall and NAT configurations passive mode has
116 a better chance of working. However, in some rare firewall
117 configurations, active mode actually works when passive mode
118 doesn't. Some really old FTP servers might not implement passive
119 transfers. If not specified, then the transfer mode is set by the
120 environment variable "FTP_PASSIVE" or if that one is not set by the
121 settings done by the libnetcfg utility. If none of these apply
122 then passive mode is used.
123 Hash - If given a reference to a file handle (e.g., "\*STDERR"),
125 print hash marks (#) on that filehandle every 1024 bytes. This
126 simply invokes the "hash()" method for you, so that hash marks are
127 displayed for all transfers. You can, of course, call "hash()"
128 explicitly whenever you'd like.
129 LocalAddr - Local address to use for all socket connections. This
131 argument will be passed to the super class, i.e. IO::Socket::INET
132 or IO::Socket::IP.
133 Domain - Domain to use, i.e. AF_INET or AF_INET6. This argument
135 will be passed to the IO::Socket super class. This can be used to
136 enforce IPv4 even with IO::Socket::IP which would default to IPv6.
137 Family is accepted as alternative name for Domain.
138 If the constructor fails undef will be returned and an error
140 message will be in $@
141 Object Methods
143 Unless otherwise stated all methods return either a true or false
144 value, with true meaning that the operation was a success. When a
145 method states that it returns a value, failure will be returned as
146 undef or an empty list.
147 "Net::FTP" inherits from "Net::Cmd" so methods defined in "Net::Cmd"
149 may be used to send commands to the remote FTP server in addition to
150 the methods documented here.
151 "login([$login[, $password[, $account]]])"
153 Log into the remote FTP server with the given login information. If
154 no arguments are given then the "Net::FTP" uses the "Net::Netrc"
155 package to lookup the login information for the connected host. If
156 no information is found then a login of anonymous is used. If no
157 password is given and the login is anonymous then anonymous@ will
158 be used for password.
159 If the connection is via a firewall then the "authorize" method
161 will be called with no arguments.
162 "starttls()"
164 Upgrade existing plain connection to SSL. The SSL arguments have
165 to be given in "new" already because they are needed for data
166 connections too.
167 "stoptls()"
169 Downgrade existing SSL connection back to plain. This is needed to
170 work with some FTP helpers at firewalls, which need to see the PORT
171 and PASV commands and responses to dynamically open the necessary
172 ports. In this case "starttls" is usually only done to protect the
173 authorization.
174 "prot($level)"
176 Set what type of data channel protection the client and server will
177 be using. Only $levels "C" (clear) and "P" (private) are
178 supported.
179 "host()"
181 Returns the value used by the constructor, and passed to the
182 IO::Socket super class to connect to the host.
183 "account($acct)"
185 Set a string identifying the user's account.
186 "authorize([$auth[, $resp]])"
188 This is a protocol used by some firewall ftp proxies. It is used to
189 authorise the user to send data out. If both arguments are not
190 specified then "authorize" uses "Net::Netrc" to do a lookup.
191 "site($args)"
193 Send a SITE command to the remote server and wait for a response.
194 Returns most significant digit of the response code.
196 "ascii()"
198 Transfer file in ASCII. CRLF translation will be done if required
199 "binary()"
201 Transfer file in binary mode. No transformation will be done.
202 Hint: If both server and client machines use the same line ending
204 for text files, then it will be faster to transfer all files in
205 binary mode.
206 "type([$type])"
208 Set or get if files will be transferred in ASCII or binary mode.
209 "rename($oldname, $newname)"
211 Rename a file on the remote FTP server from $oldname to $newname.
212 This is done by sending the RNFR and RNTO commands.
213 "delete($filename)"
215 Send a request to the server to delete $filename.
216 "cwd([$dir])"
218 Attempt to change directory to the directory given in $dir. If
219 $dir is "..", the FTP "CDUP" command is used to attempt to move up
220 one directory. If no directory is given then an attempt is made to
221 change the directory to the root directory.
222 "cdup()"
224 Change directory to the parent of the current directory.
225 "passive([$passive])"
227 Set or get if data connections will be initiated in passive mode.
228 "pwd()"
230 Returns the full pathname of the current directory.
231 "restart($where)"
233 Set the byte offset at which to begin the next data transfer.
234 Net::FTP simply records this value and uses it when during the next
235 data transfer. For this reason this method will not return an
236 error, but setting it may cause a subsequent data transfer to fail.
237 "rmdir($dir[, $recurse])"
239 Remove the directory with the name $dir. If $recurse is true then
240 "rmdir" will attempt to delete everything inside the directory.
241 "mkdir($dir[, $recurse])"
243 Create a new directory with the name $dir. If $recurse is true then
244 "mkdir" will attempt to create all the directories in the given
245 path.
246 Returns the full pathname to the new directory.
248 "alloc($size[, $record_size])"
250 The alloc command allows you to give the ftp server a hint about
251 the size of the file about to be transferred using the ALLO ftp
252 command. Some storage systems use this to make intelligent
253 decisions about how to store the file. The $size argument
254 represents the size of the file in bytes. The $record_size argument
255 indicates a maximum record or page size for files sent with a
256 record or page structure.
257 The size of the file will be determined, and sent to the server
259 automatically for normal files so that this method need only be
260 called if you are transferring data from a socket, named pipe, or
261 other stream not associated with a normal file.
262 "ls([$dir])"
264 Get a directory listing of $dir, or the current directory.
265 In an array context, returns a list of lines returned from the
267 server. In a scalar context, returns a reference to a list.
268 "dir([$dir])"
270 Get a directory listing of $dir, or the current directory in long
271 format.
272 In an array context, returns a list of lines returned from the
274 server. In a scalar context, returns a reference to a list.
275 "get($remote_file[, $local_file[, $where]])"
277 Get $remote_file from the server and store locally. $local_file may
278 be a filename or a filehandle. If not specified, the file will be
279 stored in the current directory with the same leafname as the
280 remote file.
281 If $where is given then the first $where bytes of the file will not
283 be transferred, and the remaining bytes will be appended to the
284 local file if it already exists.
285 Returns $local_file, or the generated local file name if
287 $local_file is not given. If an error was encountered undef is
288 returned.
289 "put($local_file[, $remote_file])"
291 Put a file on the remote server. $local_file may be a name or a
292 filehandle. If $local_file is a filehandle then $remote_file must
293 be specified. If $remote_file is not specified then the file will
294 be stored in the current directory with the same leafname as
295 $local_file.
296 Returns $remote_file, or the generated remote filename if
298 $remote_file is not given.
299 NOTE: If for some reason the transfer does not complete and an
301 error is returned then the contents that had been transferred will
302 not be remove automatically.
303 "put_unique($local_file[, $remote_file])"
305 Same as put but uses the "STOU" command.
306 Returns the name of the file on the server.
308 "append($local_file[, $remote_file])"
310 Same as put but appends to the file on the remote server.
311 Returns $remote_file, or the generated remote filename if
313 $remote_file is not given.
314 "unique_name()"
316 Returns the name of the last file stored on the server using the
317 "STOU" command.
318 "mdtm($file)"
320 Returns the modification time of the given file
321 "size($file)"
323 Returns the size in bytes for the given file as stored on the
324 remote server.
325 NOTE: The size reported is the size of the stored file on the
327 remote server. If the file is subsequently transferred from the
328 server in ASCII mode and the remote server and local machine have
329 different ideas about "End Of Line" then the size of file on the
330 local machine after transfer may be different.
331 "supported($cmd)"
333 Returns TRUE if the remote server supports the given command.
334 "hash([$filehandle_glob_ref[, $bytes_per_hash_mark]])"
336 Called without parameters, or with the first argument false, hash
337 marks are suppressed. If the first argument is true but not a
338 reference to a file handle glob, then \*STDERR is used. The second
339 argument is the number of bytes per hash mark printed, and defaults
340 to 1024. In all cases the return value is a reference to an array
341 of two: the filehandle glob reference and the bytes per hash mark.
342 "feature($name)"
344 Determine if the server supports the specified feature. The return
345 value is a list of lines the server responded with to describe the
346 options that it supports for the given feature. If the feature is
347 unsupported then the empty list is returned.
348 if ($ftp->feature( 'MDTM' )) {
350 # Do something
351 }
352 if (grep { /\bTLS\b/ } $ftp->feature('AUTH')) {
354 # Server supports TLS
355 }
356 The following methods can return different results depending on how
358 they are called. If the user explicitly calls either of the "pasv" or
359 "port" methods then these methods will return a true or false value. If
360 the user does not call either of these methods then the result will be
361 a reference to a "Net::FTP::dataconn" based object.
362 "nlst([$dir])"
364 Send an "NLST" command to the server, with an optional parameter.
365 "list([$dir])"
367 Same as "nlst" but using the "LIST" command
368 "retr($file)"
370 Begin the retrieval of a file called $file from the remote server.
371 "stor($file)"
373 Tell the server that you wish to store a file. $file is the name of
374 the new file that should be created.
375 "stou($file)"
377 Same as "stor" but using the "STOU" command. The name of the unique
378 file which was created on the server will be available via the
379 "unique_name" method after the data connection has been closed.
380 "appe($file)"
382 Tell the server that we want to append some data to the end of a
383 file called $file. If this file does not exist then create it.
384 If for some reason you want to have complete control over the data
386 connection, this includes generating it and calling the "response"
387 method when required, then the user can use these methods to do so.
388 However calling these methods only affects the use of the methods above
390 that can return a data connection. They have no effect on methods
391 "get", "put", "put_unique" and those that do not require data
392 connections.
393 "port([$port])"
395 "eprt([$port])"
396 Send a "PORT" (IPv4) or "EPRT" (IPv6) command to the server. If
397 $port is specified then it is sent to the server. If not, then a
398 listen socket is created and the correct information sent to the
399 server.
400 "pasv()"
402 "epsv()"
403 Tell the server to go into passive mode ("pasv" for IPv4, "epsv"
404 for IPv6). Returns the text that represents the port on which the
405 server is listening, this text is in a suitable form to send to
406 another ftp server using the "port" or "eprt" method.
407 The following methods can be used to transfer files between two remote
409 servers, providing that these two servers can connect directly to each
410 other.
411 "pasv_xfer($src_file, $dest_server[, $dest_file ])"
413 This method will do a file transfer between two remote ftp servers.
414 If $dest_file is omitted then the leaf name of $src_file will be
415 used.
416 "pasv_xfer_unique($src_file, $dest_server[, $dest_file ])"
418 Like "pasv_xfer" but the file is stored on the remote server using
419 the STOU command.
420 "pasv_wait($non_pasv_server)"
422 This method can be used to wait for a transfer to complete between
423 a passive server and a non-passive server. The method should be
424 called on the passive server with the "Net::FTP" object for the
425 non-passive server passed as an argument.
426 "abort()"
428 Abort the current data transfer.
429 "quit()"
431 Send the QUIT command to the remote FTP server and close the socket
432 connection.
433 Methods for the Adventurous
435 "quot($cmd[, $args])"
436 Send a command, that Net::FTP does not directly support, to the
437 remote server and wait for a response.
438 Returns most significant digit of the response code.
440 WARNING This call should only be used on commands that do not
442 require data connections. Misuse of this method can hang the
443 connection.
444 "can_inet6()"
446 Returns whether we can use IPv6.
447 "can_ssl()"
449 Returns whether we can use SSL.
450 The dataconn Class
452 Some of the methods defined in "Net::FTP" return an object which will
453 be derived from the "Net::FTP::dataconn" class. See Net::FTP::dataconn
454 for more details.
455 Unimplemented
457 The following RFC959 commands have not been implemented:
458 "SMNT"
460 Mount a different file system structure without changing login or
461 accounting information.
462 "HELP"
464 Ask the server for "helpful information" (that's what the RFC says)
465 on the commands it accepts.
466 "MODE"
468 Specifies transfer mode (stream, block or compressed) for file to
469 be transferred.
470 "SYST"
472 Request remote server system identification.
473 "STAT"
475 Request remote server status.
476 "STRU"
478 Specifies file structure for file to be transferred.
479 "REIN"
481 Reinitialize the connection, flushing all I/O and account
482 information.
483
485 For an example of the use of Net::FTP see
486 <https://www.csh.rit.edu/~adam/Progs/>
488 "autoftp" is a program that can retrieve, send, or list files via
489 the FTP protocol in a non-interactive manner.
490
492 None.
493
495 See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
496 Reporting Bugs
498 When reporting bugs/problems please include as much information as
499 possible. It may be difficult for me to reproduce the problem as
500 almost every setup is different.
501 A small script which yields the problem will probably be of help. It
503 would also be useful if this script was run with the extra options
504 "Debug => 1" passed to the constructor, and the output sent with the
505 bug report. If you cannot include a small script then please include a
506 Debug trace from a run of your program which does yield the problem.
507
509 Net::Netrc, Net::Cmd, IO::Socket::SSL;
510 ftp(1), ftpd(8);
512 <https://www.ietf.org/rfc/rfc959.txt>,
514 <https://www.ietf.org/rfc/rfc2428.txt>,
515 <https://www.ietf.org/rfc/rfc4217.txt>.
516
518 Henry Gabryjelski <henryg@WPI.EDU <mailto:henryg@WPI.EDU>> - for the
519 suggestion of creating directories recursively.
520 Nathan Torkington <gnat@frii.com <mailto:gnat@frii.com>> - for some
522 input on the documentation.
523 Roderick Schertler <roderick@gate.net <mailto:roderick@gate.net>> - for
525 various inputs
526
528 Graham Barr <gbarr@pobox.com <mailto:gbarr@pobox.com>>.
529 Steve Hay <shay@cpan.org <mailto:shay@cpan.org>> is now maintaining
531 libnet as of version 1.22_02.
532
534 Copyright (C) 1995-2004 Graham Barr. All rights reserved.
535 Copyright (C) 2013-2017, 2020 Steve Hay. All rights reserved.
537
539 This module is free software; you can redistribute it and/or modify it
540 under the same terms as Perl itself, i.e. under the terms of either the
541 GNU General Public License or the Artistic License, as specified in the
542 LICENCE file.
543
545 Version 3.13
546
548 23 Dec 2020
549
551 See the Changes file.
552perl v5.32.0 2021-01-04 Net::FTP(3)