1NAME
2 Net::uFTP - Universal interface for FTP-like modules (FTP, SFTP, SCP),
3 in most cases Net::FTP compatible.
4
5SYNOPSIS
6 use Net::uFTP;
7
8 my $ftp = Net::uFTP->new('some.host.name', type => 'FTP', debug => 1);
9
10 $ftp->login('mylogin','mysecret')
11 or die 'Incorrect password or login!';
12
13 $ftp->cwd("/pub")
14 or die "Cannot change working directory ", $ftp->message;
15
16 $ftp->get("that.file")
17 or die "get failed ", $ftp->message;
18
19 my $recurse = 1;
20 $ftp->get("that.dir", "this.path", $recurse)
21 or die "get failed ", $ftp->message;
22
23 $ftp->quit;
24
25DESCRIPTION
26 This module provides common interface (Net::FTP compatible) to popular
27 FTP-like protocols (for now: FTP, SFTP, SCP). Flexibility of this module
28 allows to add plugins to support other protocols (suggestions and
29 plugins are welcome ;)
30
31 Currently "Net::uFTP" was successfuly tested for compatibility with
32 "Gtk2", "Gtk2::GladeXML", "Gtk2::GladeXML::OO" and pragma "encoding
33 'utf-8'". Other modules (some Pure Perl implementations) have problems
34 with that. Consider this, when You're planning to build Gtk2 /
35 multilingual application.
36
37ATTENTION
38 "Net::uFTP" uses, for speed reason, Net::SSH2, so You have to have
39 installed libssh (<http://www.libssh2.org>). Consider, that "Net::SSH2"
40 module is available on all most popular platforms (Linux, Windows, Mac,
41 etc.), so You shouldn't have any trouble with this dependency.
42
43 If You are looking for "Pure Perl" implementation, take a look at
44 "Net::xFTP" (based on Net::SSH::Perl) instead.
45
46OVERVIEW
47 Rest of this documentation is based on "Net::FTP" documentation and
48 describes subroutines/methods available in "Net::uFTP".
49
50 Original version of this document (which describes "Net::FTP") is
51 avaliable at <http://cpan.uwinnipeg.ca/htdocs/libnet/Net/FTP.html>.
52
53CONSTRUCTOR
54 new ( HOST, OPTIONS )
55 This is the constructor for a new Net::FTP object. "HOST" is the
56 name of the remote host to which an FTP connection is required.
57
58 "OPTIONS" are passed in a hash like fashion, using key and value
59 pairs. Possible options are:
60
61 Host - FTP host to connect to. The "host" method will return the
62 value which was used to connect to the host.
63
64 debug - debug level (see the debug method in Net::Cmd)
65
66 type - type of connection. Possible values: FTP, SFTP, SCP. Default
67 to FTP.
68
69 port - the port number to connect to on the remote machine.
70
71 If the constructor fails undef will be returned and an error message
72 will be in $@
73
74METHODS
75 Unless otherwise stated all methods return either a *true* or *false*
76 value, with *true* meaning that the operation was a success. When a
77 method states that it returns a value, failure will be returned as
78 *undef* or an empty list.
79
80 login ([LOGIN [,PASSWORD [, ACCOUNT] ] ])
81 Log into the remote FTP server with the given login information.
82
83 ascii
84 Transfer file in ASCII. CRLF translation will be done if required
85
86 binary
87 Transfer file in binary mode. No transformation will be done.
88
89 Hint: If both server and client machines use the same line ending
90 for text files, then it will be faster to transfer all files in
91 binary mode.
92
93 rename ( OLDNAME, NEWNAME )
94 Rename a file on the remote FTP server from "OLDNAME" to "NEWNAME".
95 This is done by sending the RNFR and RNTO commands.
96
97 delete ( FILENAME )
98 Send a request to the server to delete "FILENAME".
99
100 cwd ( [ DIR ] )
101 Attempt to change directory to the directory given in $dir. If $dir
102 is "..", the FTP "CDUP" command is used to attempt to move up one
103 directory. If no directory is given then an attempt is made to
104 change the directory to the root directory.
105
106 cdup ()
107 Change directory to the parent of the current directory.
108
109 pwd ()
110 Returns the full pathname of the current directory.
111
112 rmdir ( DIR [, RECURSE ])
113 Remove the directory with the name "DIR". If "RECURSE" is *true*
114 then "rmdir" will attempt to delete everything inside the directory.
115
116 mkdir ( DIR [, RECURSE ])
117 Create a new directory with the name "DIR". If "RECURSE" is *true*
118 then "mkdir" will attempt to create all the directories in the given
119 path.
120
121 Returns the full pathname to the new directory.
122
123 ls ( [ DIR ] )
124 Get a directory listing of "DIR", or the current directory.
125
126 In an array context, returns a list of lines returned from the
127 server. In a scalar context, returns a reference to a list.
128
129 dir ( [ DIR ] )
130 Get a directory listing of "DIR", or the current directory in long
131 format.
132
133 In an array context, returns a list of lines returned from the
134 server. In a scalar context, returns a reference to a list.
135
136 get ( REMOTE_FILE [, LOCAL_FILE [, RECURSE ] ] )
137 Get "REMOTE_FILE" from the server and store locally. If not
138 specified, the file will be stored in the current directory with the
139 same leafname as the remote file. If "RECURSE" is *true* then "get"
140 will attempt to get directory recursively.
141
142 Returns "LOCAL_FILE", or the generated local file name if
143 "LOCAL_FILE" is not given. If an error was encountered undef is
144 returned.
145
146 put ( LOCAL_FILE [, REMOTE_FILE [, RECURSE ] ] )
147 Put a file on the remote server. "LOCAL_FILE" may be a regular file
148 or a directory. If "REMOTE_FILE" is not specified then the file will
149 be stored in the current directory with the same leafname as
150 "LOCAL_FILE". If "RECURSE" is *true* then "get" will attempt to put
151 directory recursively.
152
153 Returns "REMOTE_FILE", or the generated remote filename if
154 "REMOTE_FILE" is not given.
155
156 NOTE: If for some reason the transfer does not complete and an error
157 is returned then the contents that had been transfered will not be
158 remove automatically.
159
160 mdtm ( FILE )
161 Returns the *modification time* of the given file.
162
163 size ( FILE )
164 Returns the size in bytes for the given file as stored on the remote
165 server.
166
167 NOTE: The size reported is the size of the stored file on the remote
168 server. If the file is subsequently transfered from the server in
169 ASCII mode and the remote server and local machine have different
170 ideas about "End Of Line" then the size of file on the local machine
171 after transfer may be different.
172
173 If for some reason you want to have complete control over the data
174 connection, then the user can use these methods to do so.
175
176 However calling these methods only affects the use of the methods above
177 that can return a data connection. They have no effect on methods "get",
178 "put", "put_unique" and those that do not require data connections.
179
180 port ( [ PORT ] )
181 Send a "PORT" command to the server. If "PORT" is specified then it
182 is sent to the server. If not, then a listen socket is created and
183 the correct information sent to the server.
184
185 pasv ()
186 Tell the server to go into passive mode. Returns the text that
187 represents the port on which the server is listening, this text is
188 in a suitable form to sent to another ftp server using the "port"
189 method.
190
191 quit ()
192 Send the QUIT command to the remote FTP server and close the socket
193 connection.
194
195 "Net::uFTP" provides also useful, not "Net::FTP" compatible methods, as
196 follow:
197
198 is_dir ( REMOTE )
199 Returns true if REMOTE is a directory.
200
201 is_file ( REMOTE )
202 Returns true if REMOTE is a regular file.
203
204 change_root ( DIR )
205 Change root directory of current user. Only available in SFTP
206 environment.
207
208TODO
209 Add support for other methods from Net::FTP.
210
211REPORTING BUGS
212 When reporting bugs/problems please include as much information as
213 possible. It may be difficult for me to reproduce the problem as almost
214 every setup is different.
215
216 A small script which yields the problem will probably be of help. It
217 would also be useful if this script was run with the extra options
218 "debug =" 1> passed to the constructor, and the output sent with the bug
219 report. If you cannot include a small script then please include a debug
220 trace from a run of your program which does yield the problem.
221
222THANKS
223 Ryan Gorsuch for reaporting a bug as well as supplying relevant patch.
224
225AUTHOR
226 Strzelecki £ukasz <lukasz@strzeleccy.eu>
227
228SEE ALSO
229 Net::xFTP Net::FTP Net::SSH2
230
231COPYRIGHT
232 Copyright (c) Strzelecki Łukasz. All rights reserved. This program is
233 free software; you can redistribute it and/or modify it under the same
234 terms as Perl itself.
235
236