1Net::FTP(3)           User Contributed Perl Documentation          Net::FTP(3)
2
3
4

NAME

6       Net::FTP - FTP Client class
7

SYNOPSIS

9           use Net::FTP;
10
11           $ftp = Net::FTP->new("some.host.name", Debug => 0)
12             or die "Cannot connect to some.host.name: $@";
13
14           $ftp->login("anonymous",'-anonymous@')
15             or die "Cannot login ", $ftp->message;
16
17           $ftp->cwd("/pub")
18             or die "Cannot change working directory ", $ftp->message;
19
20           $ftp->get("that.file")
21             or die "get failed ", $ftp->message;
22
23           $ftp->quit;
24

DESCRIPTION

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
33       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
44       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
51       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

CONSTRUCTOR

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
70           "HOST" is optional. If "HOST" is not given then it may instead be
71           passed as the "Host" option described below.
72
73           "OPTIONS" are passed in a hash like fashion, using key and value
74           pairs.  Possible options are:
75
76           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
81           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
88           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
93           BlockSize - This is the block size that Net::FTP will use when
94           doing transfers. (defaults to 10240)
95
96           Port - The port number to connect to on the remote machine for the
97           FTP connection
98
99           SSL - If the connection should be done from start with SSL,
100           contrary to later upgrade with "starttls".
101
102           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
107           Timeout - Set a timeout value in seconds (defaults to 120)
108
109           Debug - debug level (see the debug method in Net::Cmd)
110
111           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
124           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
130           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
134           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
139           If the constructor fails undef will be returned and an error
140           message will be in $@
141

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
148       "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
152       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
160           If the connection is via a firewall then the "authorize" method
161           will be called with no arguments.
162
163       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
168       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
175       prot ( LEVEL )
176           Set what type of data channel protection the client and server will
177           be using.  Only "LEVEL"s "C" (clear) and "P" (private) are
178           supported.
179
180       host ()
181           Returns the value used by the constructor, and passed to the
182           IO::Socket super class to connect to the host.
183
184       account( ACCT )
185           Set a string identifying the user's account.
186
187       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
192       site (ARGS)
193           Send a SITE command to the remote server and wait for a response.
194
195           Returns most significant digit of the response code.
196
197       ascii ()
198           Transfer file in ASCII. CRLF translation will be done if required
199
200       binary ()
201           Transfer file in binary mode. No transformation will be done.
202
203           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
207       type ( [ TYPE ] )
208           Set or get if files will be transferred in ASCII or binary mode.
209
210       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
214       delete ( FILENAME )
215           Send a request to the server to delete "FILENAME".
216
217       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
223       cdup ()
224           Change directory to the parent of the current directory.
225
226       passive ( [ PASSIVE ] )
227           Set or get if data connections will be initiated in passive mode.
228
229       pwd ()
230           Returns the full pathname of the current directory.
231
232       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
238       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
242       mkdir ( DIR [, RECURSE ])
243           Create a new directory with the name "DIR". If "RECURSE" is true
244           then "mkdir" will attempt to create all the directories in the
245           given path.
246
247           Returns the full pathname to the new directory.
248
249       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"
255           argument indicates a maximum record or page size for files sent
256           with a record or page structure.
257
258           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
263       ls ( [ DIR ] )
264           Get a directory listing of "DIR", or the current directory.
265
266           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
269       dir ( [ DIR ] )
270           Get a directory listing of "DIR", or the current directory in long
271           format.
272
273           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
276       get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]] )
277           Get "REMOTE_FILE" from the server and store locally. "LOCAL_FILE"
278           may be a filename or a filehandle. If not specified, the file will
279           be stored in the current directory with the same leafname as the
280           remote file.
281
282           If "WHERE" is given then the first "WHERE" bytes of the file will
283           not be transferred, and the remaining bytes will be appended to the
284           local file if it already exists.
285
286           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
290       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"
293           must be specified. If "REMOTE_FILE" is not specified then the file
294           will be stored in the current directory with the same leafname as
295           "LOCAL_FILE".
296
297           Returns "REMOTE_FILE", or the generated remote filename if
298           "REMOTE_FILE" is not given.
299
300           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
304       put_unique ( LOCAL_FILE [, REMOTE_FILE ] )
305           Same as put but uses the "STOU" command.
306
307           Returns the name of the file on the server.
308
309       append ( LOCAL_FILE [, REMOTE_FILE ] )
310           Same as put but appends to the file on the remote server.
311
312           Returns "REMOTE_FILE", or the generated remote filename if
313           "REMOTE_FILE" is not given.
314
315       unique_name ()
316           Returns the name of the last file stored on the server using the
317           "STOU" command.
318
319       mdtm ( FILE )
320           Returns the modification time of the given file
321
322       size ( FILE )
323           Returns the size in bytes for the given file as stored on the
324           remote server.
325
326           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
332       supported ( CMD )
333           Returns TRUE if the remote server supports the given command.
334
335       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
343       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
349             if ($ftp->feature( 'MDTM' )) {
350               # Do something
351             }
352
353             if (grep { /\bTLS\b/ } $ftp->feature('AUTH')) {
354               # Server supports TLS
355             }
356
357       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
363       nlst ( [ DIR ] )
364           Send an "NLST" command to the server, with an optional parameter.
365
366       list ( [ DIR ] )
367           Same as "nlst" but using the "LIST" command
368
369       retr ( FILE )
370           Begin the retrieval of a file called "FILE" from the remote server.
371
372       stor ( FILE )
373           Tell the server that you wish to store a file. "FILE" is the name
374           of the new file that should be created.
375
376       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
381       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
385       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
389       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
394       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
401       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
408       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
412       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
417       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
421       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
427       abort ()
428           Abort the current data transfer.
429
430       quit ()
431           Send the QUIT command to the remote FTP server and close the socket
432           connection.
433
434   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
439           Returns most significant digit of the response code.
440
441           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
445       can_inet6 ()
446           Returns whether we can use IPv6.
447
448       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
459       SMNT
460           Mount a different file system structure without changing login or
461           accounting information.
462
463       HELP
464           Ask the server for "helpful information" (that's what the RFC says)
465           on the commands it accepts.
466
467       MODE
468           Specifies transfer mode (stream, block or compressed) for file to
469           be transferred.
470
471       SYST
472           Request remote server system identification.
473
474       STAT
475           Request remote server status.
476
477       STRU
478           Specifies file structure for file to be transferred.
479
480       REIN
481           Reinitialize the connection, flushing all I/O and account
482           information.
483

REPORTING BUGS

485       When reporting bugs/problems please include as much information as
486       possible.  It may be difficult for me to reproduce the problem as
487       almost every setup is different.
488
489       A small script which yields the problem will probably be of help. It
490       would also be useful if this script was run with the extra options
491       "Debug => 1" passed to the constructor, and the output sent with the
492       bug report. If you cannot include a small script then please include a
493       Debug trace from a run of your program which does yield the problem.
494

AUTHOR

496       Graham Barr <gbarr@pobox.com>.
497
498       Steve Hay <shay@cpan.org> is now maintaining libnet as of version
499       1.22_02.
500

SEE ALSO

502       Net::Netrc, Net::Cmd, IO::Socket::SSL
503
504       ftp(1), ftpd(8), RFC 959, RFC 2428, RFC 4217
505       http://www.ietf.org/rfc/rfc959.txt http://www.ietf.org/rfc/rfc2428.txt
506       http://www.ietf.org/rfc/rfc4217.txt
507

USE EXAMPLES

509       For an example of the use of Net::FTP see
510
511       http://www.csh.rit.edu/~adam/Progs/
512           "autoftp" is a program that can retrieve, send, or list files via
513           the FTP protocol in a non-interactive manner.
514

CREDITS

516       Henry Gabryjelski <henryg@WPI.EDU> - for the suggestion of creating
517       directories recursively.
518
519       Nathan Torkington <gnat@frii.com> - for some input on the
520       documentation.
521
522       Roderick Schertler <roderick@gate.net> - for various inputs
523
525       Copyright (C) 1995-2004 Graham Barr.  All rights reserved.
526
527       Copyright (C) 2013-2017 Steve Hay.  All rights reserved.
528

LICENCE

530       This module is free software; you can redistribute it and/or modify it
531       under the same terms as Perl itself, i.e. under the terms of either the
532       GNU General Public License or the Artistic License, as specified in the
533       LICENCE file.
534
535
536
537perl v5.28.0                      2017-11-14                       Net::FTP(3)
Impressum