1ftp(3) Erlang Module Definition ftp(3)
2
6 ftp - A File Transfer Protocol client.
7
9 This module implements a client for file transfer according to a subset
10 of the File Transfer Protocol (FTP), see RFC 959.
11 The FTP client always tries to use passive FTP mode and only resort to
13 active FTP mode if this fails. This default behavior can be changed by
14 start option mode.
15 For a simple example of an FTP session, see FTP User's Guide.
17 In addition to the ordinary functions for receiving and sending files
19 (see recv/2, recv/3, send/2, and send/3) there are functions for re‐
20 ceiving remote files as binaries (see recv_bin/2) and for sending bina‐
21 ries to be stored as remote files (see send_bin/3).
22 A set of functions is provided for sending and receiving contiguous
24 parts of a file to be stored in a remote file. For send, see
25 send_chunk_start/2, send_chunk/2, and send_chunk_end/1. For receive,
26 see recv_chunk_start/2 and recv_chunk/).
27 The return values of the following functions depend much on the imple‐
29 mentation of the FTP server at the remote host. In particular, the re‐
30 sults from ls and nlist varies. Often real errors are not reported as
31 errors by ls, even if, for example, a file or directory does not exist.
32 nlist is usually more strict, but some implementations have the pecu‐
33 liar behaviour of responding with an error if the request is a listing
34 of the contents of a directory that exists but is empty.
35
37 The FTP client can be started and stopped dynamically in runtime by
38 calling the ftp application API ftp:open(Host, Options) and
39 ftp:close(Client).
40
42 The following type definitions are used by more than one function in
43 the FTP client API:
44 pid() = identifier of an FTP connection
46 string() = list of ASCII characters
48
50 account(Pid :: pid(), Acc :: string()) ->
51 ok | {error, Reason :: term()}
52 Sets the account for an operation, if needed.
54 append(Pid :: pid(), LocalFileName :: string()) ->
56 ok | {error, Reason :: term()}
57 append(Pid :: pid(),
59 LocalFileName :: string(),
60 RemoteFileName :: string()) ->
61 ok | {error, Reason :: term()}
62 Transfers the file LocalFile to the remote server. If RemoteFile
64 is specified, the name of the remote file that the file is ap‐
65 pended to is set to RemoteFile, otherwise to LocalFile. If the
66 file does not exists, it is created.
67 append_bin(Pid :: pid(), Bin :: binary(), RemoteFile :: string()) ->
69 ok | {error, Reason :: term()}
70 Transfers the binary Bin to the remote server and appends it to
72 the file RemoteFile. If the file does not exist, it is created.
73 append_chunk(Pid :: pid(), Bin :: binary()) ->
75 ok | {error, Reason :: term()}
76 Transfers the chunk Bin to the remote server, which appends it
78 to the file specified in the call to append_chunk_start/2.
79 For some errors, for example, file system full, it is necessary
81 to call append_chunk_end to get the proper reason.
82 append_chunk_start(Pid :: pid(), RemoteFile :: string()) ->
84 ok | {error, Reason :: term()}
85 Starts the transfer of chunks for appending to the file Remote‐
87 File at the remote server. If the file does not exist, it is
88 created.
89 append_chunk_end(Pid :: pid()) -> ok | {error, Reason :: term()}
91 Stops transfer of chunks for appending to the remote server. The
93 file at the remote server, specified in the call to ap‐
94 pend_chunk_start/2, is closed by the server.
95 cd(Pid :: pid(), Dir :: string()) ->
97 ok | {error, Reason :: term()}
98 Changes the working directory at the remote server to Dir.
100 close(Pid :: pid()) -> ok
102 Ends an FTP session, created using function open.
104 delete(Pid :: pid(), File :: string()) ->
106 ok | {error, Reason :: term()}
107 Deletes the file File at the remote server.
109 formaterror(Tag :: atom() | {error, atom()}) -> string()
111 Given an error return value {error, AtomReason}, this function
113 returns a readable string describing the error.
114 lcd(Pid :: pid(), Dir :: string()) ->
116 ok | {error, Reason :: term()}
117 Changes the working directory to Dir for the local client.
119 lpwd(Pid :: pid()) -> {ok, Dir :: string()}
121 Returns the current working directory at the local client.
123 ls(Pid :: pid()) ->
125 {ok, Listing :: string()} | {error, Reason :: term()}
126 ls(Pid :: pid(), Dir :: string()) ->
128 {ok, Listing :: string()} | {error, Reason :: term()}
129 Returns a list of files in long format.
131 Dir can be a directory or a file. The Dir string can contain
133 wildcards.
134 ls/1 implies the current remote directory of the user.
136 The format of Listing depends on the operating system. On UNIX,
138 it is typically produced from the output of the ls -l shell com‐
139 mand.
140 mkdir(Pid :: pid(), Dir :: string()) ->
142 ok | {error, Reason :: term()}
143 Creates the directory Dir at the remote server.
145 nlist(Pid :: pid()) ->
147 {ok, Listing :: string()} | {error, Reason :: term()}
148 nlist(Pid :: pid(), Pathname :: string()) ->
150 {ok, Listing :: string()} | {error, Reason :: term()}
151 Returns a list of files in short format.
153 Pathname can be a directory or a file. The Pathname string can
155 contain wildcards.
156 nlist/1 implies the current remote directory of the user.
158 The format of Listing is a stream of filenames where each file‐
160 name is separated by <CRLF> or <NL>. Contrary to function ls,
161 the purpose of nlist is to enable a program to process filename
162 information automatically.
163 open(Host :: string() | inet:ip_address()) ->
165 {ok, Pid :: pid()} | {error, Reason :: term()}
166 open(Host :: string() | inet:ip_address(), Opts) ->
168 {ok, Pid :: pid()} | {error, Reason :: term()}
169 Types:
171 Opts = [Opt]
173 Opt = StartOption | OpenOption
174 StartOption = {verbose, Verbose} | {debug, Debug}
175 Verbose = boolean()
176 Debug = disable | debug | trace
177 OpenOption =
178 {ipfamily, IpFamily} |
179 {port, Port :: port()} |
180 {mode, Mode} |
181 {tls, TLSOptions :: [ssl:tls_option()]} |
182 {tls_sec_method, TLSSecMethod :: ftps | ftpes} |
183 {tls_ctrl_session_reuse, TLSSessionReuse :: boolean()} |
184 {timeout, Timeout :: timeout()} |
185 {dtimeout, DTimeout :: timeout()} |
186 {progress, Progress} |
187 {sock_ctrl, SocketCtrls} |
188 {sock_data_act, [SocketControl]} |
189 {sock_data_pass, [SocketControl]}
190 SocketCtrls = [SocketControl]
191 IpFamily = inet | inet6 | inet6fb4
192 Mode = active | passive
193 Module = Function = atom()
194 InitialData = term()
195 Progress = ignore | {Module, Function, InitialData}
196 SocketControl = gen_tcp:option()
197 Starts a FTP client process and opens a session with the FTP
199 server at Host.
200 A session opened in this way is closed using function close.
202 The available configuration options are as follows:
204 {host, Host}:
206 Host = string() | ip_address()
209 {port, Port}:
211 Default is 0 which aliases to 21 or 990 when used with
214 {tls_sec_method,ftps}).
215 {mode, Mode}:
217 Default is passive.
220 {verbose, Verbose}:
222 Determines if the FTP communication is to be verbose or not.
225 Default is false.
227 {debug, Debug}:
229 Debugging using the dbg toolkit.
232 Default is disable.
234 {ipfamily, IpFamily}:
236 With inet6fb4 the client behaves as before, that is, tries
239 to use IPv6, and only if that does not work it uses IPv4).
240 Default is inet (IPv4).
242 {timeout, Timeout}:
244 Connection time-out.
247 Default is 60000 (milliseconds).
249 {dtimeout, DTimeout}:
251 Data connect time-out. The time the client waits for the
254 server to connect to the data socket.
255 Default is infinity.
257 {tls, TLSOptions}:
259 The FTP session is transported over tls (ftps, see RFC
262 4217). The list TLSOptions can be empty. The function
263 ssl:connect/3 is used for securing both the control connec‐
264 tion and the data sessions.
265 {tls_sec_method, TLSSecMethod}:
267 When set to ftps will connect immediately with SSL instead
270 of upgrading with STARTTLS. This suboption is ignored unless
271 the suboption tls is also set.
272 Default is ftpes
274 {tls_ctrl_session_reuse, boolean()}:
276 When set to true the client will re-use the TLS session from
279 the control channel on the data channel as enforced by many
280 FTP servers as (proposed and implemented first by vsftpd).
281 Default is false.
283 {sock_ctrl, SocketCtrls :: [SocketControl :: gen_tcp:op‐
285 tion()]}:
286 Passes options from SocketCtrls down to the underlying
287 transport layer (tcp).
288 gen_tcp:option() except for ipv6_v6only, active, packet,
290 mode, packet_size and header.
291 Default value is SocketCtrls = [].
293 {sock_data_act, [SocketControl]}:
295 Passes options from [SocketControl] down to the underlying
296 transport layer (tcp).
297 sock_data_act uses the value of sock_ctrl as default value.
299 {sock_data_pass, [SocketControl]}:
301 Passes options from [SocketControl] down to the underlying
302 transport layer (tcp).
303 sock_data_pass uses the value of sock_ctrl as default value.
305 {progress, Progress}:
307 Progress = ignore | {Module, Function, InitialData}
310 Module = atom(), Function = atom()
312 InitialData = term()
314 Default is ignore.
316 Option progress is intended to be used by applications that
318 want to create some type of progress report, such as a
319 progress bar in a GUI. Default for the progress option is
320 ignore, that is, the option is not used. When the progress
321 option is specified, the following happens when
322 ftp:send/[3,4] or ftp:recv/[3,4] are called:
323 * Before a file is transferred, the following call is made
325 to indicate the start of the file transfer and how large
326 the file is. The return value of the callback function is
327 to be a new value for the UserProgressTerm that will be
328 used as input the next time the callback function is
329 called.
330 Module:Function(InitialData, File, {file_size, FileSize})
332 * Every time a chunk of bytes is transferred the following
335 call is made:
336 Module:Function(UserProgressTerm, File, {transfer_size,
338 TransferSize})
339 * At the end of the file the following call is made to indi‐
341 cate the end of the transfer:
342 Module:Function(UserProgressTerm, File, {transfer_size,
344 0})
345 The callback function is to be defined as follows:
347 Module:Function(UserProgressTerm, File, Size) -> UserPro‐
349 gressTerm
350 UserProgressTerm = term()
352 File = string()
354 Size = {transfer_size, integer()} | {file_size, integer()}
356 | {file_size, unknown}
357 For remote files, ftp cannot determine the file size in a
359 platform independent way. In this case the size becomes un‐
360 known and it is left to the application to determine the
361 size.
362 Note:
364 The callback is made by a middleman process, hence the file
365 transfer is not affected by the code in the progress callback
366 function. If the callback crashes, this is detected by the FTP
367 connection process, which then prints an info-report and goes
368 on as if the progress option was set to ignore.
369 The file transfer type is set to the default of the FTP
372 server when the session is opened. This is usually ASCII
373 mode.
374 The current local working directory (compare lpwd/1) is set
376 to the value reported by file:get_cwd/1, the wanted local
377 directory.
378 The return value Pid is used as a reference to the newly
380 created FTP client in all other functions, and they are to
381 be called by the process that created the connection. The
382 FTP client process monitors the process that created it and
383 terminates if that process terminates.
384 pwd(Pid :: pid()) ->
386 {ok, Dir :: string()} | {error, Reason :: term()}
387 Returns the current working directory at the remote server.
389 recv(Pid :: pid(), RemoteFileName :: string()) ->
391 ok | {error, Reason :: term()}
392 recv(Pid :: pid(),
394 RemoteFileName :: string(),
395 LocalFileName :: string()) ->
396 ok | {error, Reason :: term()}
397 Transfers the file RemoteFileName from the remote server to the
399 file system of the local client. If LocalFileName is specified,
400 the local file will be LocalFileName, otherwise RemoteFileName.
401 If the file write fails, the command is aborted and {error,
403 term()} is returned. However, the file is not removed.
404 recv_bin(Pid :: pid(), RemoteFile :: string()) ->
406 {ok, Bin :: binary()} | {error, Reason :: term()}
407 Transfers the file RemoteFile from the remote server and re‐
409 ceives it as a binary.
410 recv_chunk_start(Pid :: pid(), RemoteFile :: string()) ->
412 ok | {error, Reason :: term()}
413 Starts transfer of the file RemoteFile from the remote server.
415 recv_chunk(Pid :: pid()) ->
417 ok |
418 {ok, Bin :: binary()} |
419 {error, Reason :: term()}
420 Receives a chunk of the remote file (RemoteFile of
422 recv_chunk_start). The return values have the following meaning:
423 * ok = the transfer is complete.
425 * {ok, Bin} = just another chunk of the file.
427 * {error, Reason} = transfer failed.
429 rename(Pid :: pid(), Old :: string(), New :: string()) ->
431 ok | {error, Reason :: term()}
432 Renames Old to New at the remote server.
434 rmdir(Pid :: pid(), Dir :: string()) ->
436 ok | {error, Reason :: term()}
437 Removes directory Dir at the remote server.
439 send(Pid :: pid(), LocalFileName :: string()) ->
441 ok | {error, Reason :: term()}
442 send(Pid :: pid(),
444 LocalFileName :: string(),
445 RemoteFileName :: string()) ->
446 ok | {error, Reason :: term()}
447 Transfers the file LocalFileName to the remote server. If Re‐
449 moteFileName is specified, the name of the remote file is set to
450 RemoteFileName, otherwise to LocalFileName.
451 send_bin(Pid :: pid(), Bin :: binary(), RemoteFile :: string()) ->
453 ok | {error, Reason :: term()}
454 Transfers the binary Bin into the file RemoteFile at the remote
456 server.
457 send_chunk(Pid :: pid(), Bin :: binary()) ->
459 ok | {error, Reason :: term()}
460 Transfers the chunk Bin to the remote server, which writes it
462 into the file specified in the call to send_chunk_start/2.
463 For some errors, for example, file system full, it is necessary
465 to to call send_chunk_end to get the proper reason.
466 send_chunk_start(Pid :: pid(), RemoteFile :: string()) ->
468 ok | {error, Reason :: term()}
469 Starts transfer of chunks into the file RemoteFile at the remote
471 server.
472 send_chunk_end(Pid :: pid()) -> ok | {error, Reason :: term()}
474 Stops transfer of chunks to the remote server. The file at the
476 remote server, specified in the call to send_chunk_start/2 is
477 closed by the server.
478 type(Pid :: pid(), Type :: ascii | binary) ->
480 ok | {error, Reason :: term()}
481 Sets the file transfer type to ascii or binary. When an FTP ses‐
483 sion is opened, the default transfer type of the server is used,
484 most often ascii, which is default according to RFC 959.
485 user(Pid :: pid(), User :: string(), Pass :: string()) ->
487 ok | {error, Reason :: term()}
488 Performs login of User with Pass.
490 user(Pid :: pid(),
492 User :: string(),
493 Pass :: string(),
494 Account :: string()) ->
495 ok | {error, Reason :: term()}
496 Performs login of User with Pass to the account specified by Ac‐
498 count.
499 quote(Pid :: pid(), Cmd :: string()) -> [FTPLine :: string()]
501 Note:
503 The telnet end of line characters, from the FTP protocol defini‐
504 tion, CRLF, for example, "\\r\\n" has been removed.
505 Sends an arbitrary FTP command and returns verbatim a list of
508 the lines sent back by the FTP server. This function is intended
509 to give application accesses to FTP commands that are server-
510 specific or that cannot be provided by this FTP client.
511 Note:
513 FTP commands requiring a data connection cannot be successfully
514 issued with this function.
515
518 The possible error reasons and the corresponding diagnostic strings re‐
519 turned by formaterror/1 are as follows:
520 echunk:
522 Synchronization error during chunk sending according to one of the
523 following:
524 * A call is made to send_chunk/2 or send_chunk_end/1 before a call
526 to send_chunk_start/2.
527 * A call has been made to another transfer function during chunk
529 sending, that is, before a call to send_chunk_end/1.
530 eclosed:
532 The session is closed.
533 econn:
535 Connection to the remote server is prematurely closed.
536 ehost:
538 Host is not found, FTP server is not found, or connection is re‐
539 jected by FTP server.
540 elogin:
542 User is not logged in.
543 enotbinary:
545 Term is not a binary.
546 epath:
548 No such file or directory, or directory already exists, or permis‐
549 sion denied.
550 etype:
552 No such type.
553 euser:
555 Invalid username or password.
556 etnospc:
558 Insufficient storage space in system [452].
559 epnospc:
561 Exceeded storage allocation (for current directory or dataset)
562 [552].
563 efnamena:
565 Filename not allowed [553].
566
568 file(3) filename(3) and J. Postel and J. Reynolds: File Transfer Proto‐
569 col (RFC 959).
570Ericsson AB ftp 1.2 ftp(3)