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 An FTP client is always started as part of the ftp application and
17 legacy start_service function, is deprecated in OTP-24
18 For a simple example of an FTP session, see FTP User's Guide.
20 In addition to the ordinary functions for receiving and sending files
22 (see recv/2, recv/3, send/2, and send/3) there are functions for re‐
23 ceiving remote files as binaries (see recv_bin/2) and for sending bina‐
24 ries to be stored as remote files (see send_bin/3).
25 A set of functions is provided for sending and receiving contiguous
27 parts of a file to be stored in a remote file. For send, see
28 send_chunk_start/2, send_chunk/2, and send_chunk_end/1. For receive,
29 see recv_chunk_start/2 and recv_chunk/).
30 The return values of the following functions depend much on the imple‐
32 mentation of the FTP server at the remote host. In particular, the re‐
33 sults from ls and nlist varies. Often real errors are not reported as
34 errors by ls, even if, for example, a file or directory does not exist.
35 nlist is usually more strict, but some implementations have the pecu‐
36 liar behaviour of responding with an error if the request is a listing
37 of the contents of a directory that exists but is empty.
38
40 The FTP client can be started and stopped dynamically in runtime by
41 calling the ftp application API ftp:open(Host, Options) and
42 ftp:close(Client).
43 The available configuration options are as follows:
45 {host, Host}:
47 Host = string() | ip_address()
50 {port, Port}:
52 Port = integer() > 0
55 Default is 0 which aliases to 21 or 990 when used with
57 {tls_sec_method,ftps}).
58 {mode, Mode}:
60 Mode = active | passive
63 Default is passive.
65 {verbose, Verbose}:
67 Verbose = boolean()
70 Determines if the FTP communication is to be verbose or not.
72 Default is false.
74 {debug, Debug}:
76 Debug = trace | debug | disable
79 Debugging using the dbg toolkit.
81 Default is disable.
83 {ipfamily, IpFamily}:
85 IpFamily = inet | inet6 | inet6fb4
88 With inet6fb4 the client behaves as before, that is, tries to use
90 IPv6, and only if that does not work it uses IPv4).
91 Default is inet (IPv4).
93 {timeout, Timeout}:
95 Timeout = non_neg_integer()
98 Connection time-out.
100 Default is 60000 (milliseconds).
102 {dtimeout, DTimeout}:
104 DTimeout = non_neg_integer() | infinity
107 Data connect time-out. The time the client waits for the server to
109 connect to the data socket.
110 Default is infinity.
112 {progress, Progress}:
114 Progress = ignore | {CBModule, CBFunction, InitProgress}
117 CBModule = atom(), CBFunction = atom()
119 InitProgress = term()
121 Default is ignore.
123 Option progress is intended to be used by applications that want to
125 create some type of progress report, such as a progress bar in a GUI.
126 Default for the progress option is ignore, that is, the option is not
127 used. When the progress option is specified, the following happens when
128 ftp:send/[3,4] or ftp:recv/[3,4] are called:
129 * Before a file is transferred, the following call is made to indi‐
131 cate the start of the file transfer and how large the file is. The
132 return value of the callback function is to be a new value for the
133 UserProgressTerm that will be used as input the next time the call‐
134 back function is called.
135 CBModule:CBFunction(InitProgress, File, {file_size, FileSize})
137 * Every time a chunk of bytes is transferred the following call is
139 made:
140 CBModule:CBFunction(UserProgressTerm, File, {transfer_size, Trans‐
142 ferSize})
143 * At the end of the file the following call is made to indicate the
145 end of the transfer:
146 CBModule:CBFunction(UserProgressTerm, File, {transfer_size, 0})
148 The callback function is to be defined as follows:
150 CBModule:CBFunction(UserProgressTerm, File, Size) -> UserProgressTerm
152 CBModule = CBFunction = atom()
154 UserProgressTerm = term()
156 File = string()
158 Size = {transfer_size, integer()} | {file_size, integer()} |
160 {file_size, unknown}
161 For remote files, ftp cannot determine the file size in a platform in‐
163 dependent way. In this case the size becomes unknown and it is left to
164 the application to determine the size.
165 Note:
167 The callback is made by a middleman process, hence the file transfer is
168 not affected by the code in the progress callback function. If the
169 callback crashes, this is detected by the FTP connection process, which
170 then prints an info-report and goes on as if the progress option was
171 set to ignore.
172 The file transfer type is set to the default of the FTP server when the
175 session is opened. This is usually ASCII mode.
176 The current local working directory (compare lpwd/1) is set to the
178 value reported by file:get_cwd/1, the wanted local directory.
179 The return value Pid is used as a reference to the newly created FTP
181 client in all other functions, and they are to be called by the process
182 that created the connection. The FTP client process monitors the
183 process that created it and terminates if that process terminates.
184
186 The following type definitions are used by more than one function in
187 the FTP client API:
188 pid() = identifier of an FTP connection
190 string() = list of ASCII characters
192 shortage_reason() = etnospc | epnospc
194 restriction_reason() = epath | efnamena | elogin | enotbinary - all re‐
196 strictions are not always relevant to all functions
197 common_reason() = econn | eclosed | term() - some explanation of what
199 went wrong
200
202 account(Pid, Account) -> ok | {error, Reason}
203 Types:
205 Pid = pid()
207 Account = string()
208 Reason = eacct | common_reason()
209 Sets the account for an operation, if needed.
211 append(Pid, LocalFile) ->
213 append(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}
214 Types:
216 Pid = pid()
218 LocalFile = RemoteFile = string()
219 Reason = epath | elogin | etnospc | epnospc | efnamena | com‐
220 mon_reason
221 Transfers the file LocalFile to the remote server. If RemoteFile
223 is specified, the name of the remote file that the file is ap‐
224 pended to is set to RemoteFile, otherwise to LocalFile. If the
225 file does not exists, it is created.
226 append_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}
228 Types:
230 Pid = pid()
232 Bin = binary()
233 RemoteFile = string()
234 Reason = restriction_reason()| shortage_reason() | com‐
235 mon_reason()
236 Transfers the binary Bin to the remote server and appends it to
238 the file RemoteFile. If the file does not exist, it is created.
239 append_chunk(Pid, Bin) -> ok | {error, Reason}
241 Types:
243 Pid = pid()
245 Bin = binary()
246 Reason = echunk | restriction_reason() | common_reason()
247 Transfers the chunk Bin to the remote server, which appends it
249 to the file specified in the call to append_chunk_start/2.
250 For some errors, for example, file system full, it is necessary
252 to call append_chunk_end to get the proper reason.
253 append_chunk_start(Pid, File) -> ok | {error, Reason}
255 Types:
257 Pid = pid()
259 File = string()
260 Reason = restriction_reason() | common_reason()
261 Starts the transfer of chunks for appending to the file File at
263 the remote server. If the file does not exist, it is created.
264 append_chunk_end(Pid) -> ok | {error, Reason}
266 Types:
268 Pid = pid()
270 Reason = echunk | restriction_reason() | shortage_reason()
271 Stops transfer of chunks for appending to the remote server. The
273 file at the remote server, specified in the call to ap‐
274 pend_chunk_start/2, is closed by the server.
275 cd(Pid, Dir) -> ok | {error, Reason}
277 Types:
279 Pid = pid()
281 Dir = string()
282 Reason = restriction_reason() | common_reason()
283 Changes the working directory at the remote server to Dir.
285 close(Pid) -> ok
287 Types:
289 Pid = pid()
291 Ends an FTP session, created using function open.
293 delete(Pid, File) -> ok | {error, Reason}
295 Types:
297 Pid = pid()
299 File = string()
300 Reason = restriction_reason() | common_reason()
301 Deletes the file File at the remote server.
303 formaterror(Tag) -> string()
305 Types:
307 Tag = {error, atom()} | atom()
309 Given an error return value {error, AtomReason}, this function
311 returns a readable string describing the error.
312 lcd(Pid, Dir) -> ok | {error, Reason}
314 Types:
316 Pid = pid()
318 Dir = string()
319 Reason = restriction_reason()
320 Changes the working directory to Dir for the local client.
322 lpwd(Pid) -> {ok, Dir}
324 Types:
326 Pid = pid()
328 Returns the current working directory at the local client.
330 ls(Pid) ->
332 ls(Pid, Pathname) -> {ok, Listing} | {error, Reason}
333 Types:
335 Pid = pid()
337 Pathname = string()
338 Listing = string()
339 Reason = restriction_reason() | common_reason()
340 Returns a list of files in long format.
342 Pathname can be a directory, a group of files, or a file. The
344 Pathname string can contain wildcards.
345 ls/1 implies the current remote directory of the user.
347 The format of Listing depends on the operating system. On UNIX,
349 it is typically produced from the output of the ls -l shell com‐
350 mand.
351 mkdir(Pid, Dir) -> ok | {error, Reason}
353 Types:
355 Pid = pid()
357 Dir = string()
358 Reason = restriction_reason() | common_reason()
359 Creates the directory Dir at the remote server.
361 nlist(Pid) ->
363 nlist(Pid, Pathname) -> {ok, Listing} | {error, Reason}
364 Types:
366 Pid = pid()
368 Pathname = string()
369 Listing = string()
370 Reason = restriction_reason() | common_reason()
371 Returns a list of files in short format.
373 Pathname can be a directory, a group of files, or a file. The
375 Pathname string can contain wildcards.
376 nlist/1 implies the current remote directory of the user.
378 The format of Listing is a stream of filenames where each file‐
380 name is separated by <CRLF> or <NL>. Contrary to function ls,
381 the purpose of nlist is to enable a program to process filename
382 information automatically.
383 open(Host) -> {ok, Pid} | {error, Reason}
385 open(Host, Opts) -> {ok, Pid} | {error, Reason}
386 Types:
388 Host = string() | ip_address()
390 Opts = options()
391 options() = [option()]
392 option() = start_option() | open_option()
393 start_option() = {verbose, verbose()} | {debug, debug()}
394 verbose() = boolean() (default is false)
395 debug() = disable | debug | trace (default is disable)
396 open_option() = {ipfamily, ipfamily()} | {port, port()} |
397 {mode, mode()} | {tls, tls_options()} | {tls_sec_method,
398 tls_sec_method()} | {tls_ctrl_session_reuse, boolean() (de‐
399 fault is false)} | {timeout, timeout()} | {dtimeout, dtime‐
400 out()} | {progress, progress()} | {sock_ctrl, sock_opts()} |
401 {sock_data_act, sock_opts()} | {sock_data_pass, sock_opts()}
402 ipfamily() = inet | inet6 | inet6fb4 (default is inet)
403 port() = non_neg_integer() (default is 0 which aliases to 21
404 or 990 when used with {tls_sec_method,ftps})
405 mode() = active | passive (default is passive)
406 tls_options() = [ssl:tls_option()]
407 tls_sec_method() = ftps | ftpes (default is ftpes)
408 sock_opts() = [gen_tcp:option() except for ipv6_v6only, ac‐
409 tive, packet, mode, packet_size and header
410 timeout() = integer() > 0 (default is 60000 milliseconds)
411 dtimeout() = integer() > 0 | infinity (default is infinity)
412 progress() = ignore | {module(), function(), initial_data()}
413 (default is ignore)
414 module() = atom()
415 function() = atom()
416 initial_data() = term()
417 Reason = ehost | term()
418 Starts a FTP client process and opens a session with the FTP
420 server at Host.
421 If option {tls, tls_options()} is present, the FTP session is
423 transported over tls (ftps, see RFC 4217). The list tls_op‐
424 tions() can be empty. The function ssl:connect/3 is used for se‐
425 curing both the control connection and the data sessions.
426 The suboption {tls_sec_method, tls_sec_method()} (defaults to
428 ftpes) when set to ftps will connect immediately with SSL in‐
429 stead of upgrading with STARTTLS. This suboption is ignored un‐
430 less the suboption tls is also set.
431 The option {tls_ctrl_session_reuse, boolean()} (defaults to
433 false) when set to true the client will re-use the TLS session
434 from the control channel on the data channel as enforced by many
435 FTP servers as (proposed and implemented first by vsftpd).
436 The options sock_ctrl, sock_data_act and sock_data_pass passes
438 options down to the underlying transport layer (tcp). The de‐
439 fault value for sock_ctrl is []. Both sock_data_act and
440 sock_data_pass uses the value of sock_ctrl as default value.
441 A session opened in this way is closed using function close.
443 pwd(Pid) -> {ok, Dir} | {error, Reason}
445 Types:
447 Pid = pid()
449 Reason = restriction_reason() | common_reason()
450 Returns the current working directory at the remote server.
452 recv(Pid, RemoteFile) ->
454 recv(Pid, RemoteFile, LocalFile) -> ok | {error, Reason}
455 Types:
457 Pid = pid()
459 RemoteFile = LocalFile = string()
460 Reason = restriction_reason() | common_reason() |
461 file_write_error_reason()
462 file_write_error_reason() = see file:write/2
463 Transfers the file RemoteFile from the remote server to the file
465 system of the local client. If LocalFile is specified, the local
466 file will be LocalFile, otherwise RemoteFile.
467 If the file write fails (for example, enospc), the command is
469 aborted and {error, file_write_error_reason()} is returned. How‐
470 ever, the file is not removed.
471 recv_bin(Pid, RemoteFile) -> {ok, Bin} | {error, Reason}
473 Types:
475 Pid = pid()
477 Bin = binary()
478 RemoteFile = string()
479 Reason = restriction_reason() | common_reason()
480 Transfers the file RemoteFile from the remote server and re‐
482 ceives it as a binary.
483 recv_chunk_start(Pid, RemoteFile) -> ok | {error, Reason}
485 Types:
487 Pid = pid()
489 RemoteFile = string()
490 Reason = restriction_reason() | common_reason()
491 Starts transfer of the file RemoteFile from the remote server.
493 recv_chunk(Pid) -> ok | {ok, Bin} | {error, Reason}
495 Types:
497 Pid = pid()
499 Bin = binary()
500 Reason = restriction_reason() | common_reason()
501 Receives a chunk of the remote file (RemoteFile of
503 recv_chunk_start). The return values have the following meaning:
504 * ok = the transfer is complete.
506 * {ok, Bin} = just another chunk of the file.
508 * {error, Reason} = transfer failed.
510 rename(Pid, Old, New) -> ok | {error, Reason}
512 Types:
514 Pid = pid()
516 CurrFile = NewFile = string()
517 Reason = restriction_reason() | common_reason()
518 Renames Old to New at the remote server.
520 rmdir(Pid, Dir) -> ok | {error, Reason}
522 Types:
524 Pid = pid()
526 Dir = string()
527 Reason = restriction_reason() | common_reason()
528 Removes directory Dir at the remote server.
530 send(Pid, LocalFile) ->
532 send(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}
533 Types:
535 Pid = pid()
537 LocalFile = RemoteFile = string()
538 Reason = restriction_reason() | common_reason() | short‐
539 age_reason()
540 Transfers the file LocalFile to the remote server. If RemoteFile
542 is specified, the name of the remote file is set to RemoteFile,
543 otherwise to LocalFile.
544 send_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}
546 Types:
548 Pid = pid()
550 Bin = binary()
551 RemoteFile = string()
552 Reason = restriction_reason() | common_reason() | short‐
553 age_reason()
554 Transfers the binary Bin into the file RemoteFile at the remote
556 server.
557 send_chunk(Pid, Bin) -> ok | {error, Reason}
559 Types:
561 Pid = pid()
563 Bin = binary()
564 Reason = echunk | restriction_reason() | common_reason()
565 Transfers the chunk Bin to the remote server, which writes it
567 into the file specified in the call to send_chunk_start/2.
568 For some errors, for example, file system full, it is necessary
570 to to call send_chunk_end to get the proper reason.
571 send_chunk_start(Pid, File) -> ok | {error, Reason}
573 Types:
575 Pid = pid()
577 File = string()
578 Reason = restriction_reason() | common_reason()
579 Starts transfer of chunks into the file File at the remote
581 server.
582 send_chunk_end(Pid) -> ok | {error, Reason}
584 Types:
586 Pid = pid()
588 Reason = restriction_reason() | common_reason() | short‐
589 age_reason()
590 Stops transfer of chunks to the remote server. The file at the
592 remote server, specified in the call to send_chunk_start/2 is
593 closed by the server.
594 start_service(ServiceConfig) -> {ok, Pid} | {error, Reason}
596 Types:
598 ServiceConfig = [{Option, Value}]
600 Option = property()
601 Value = term()
602 Dynamically starts an FTP session after the ftp application has
604 been started.
605 Note:
607 As long as the ftp application is operational, the FTP sessions
608 are supervised and can be soft code upgraded.
609 stop_service(Reference) -> ok | {error, Reason}
612 Types:
614 Reference = pid() | term() - service-specified reference
616 Reason = term()
617 Stops a started FTP session.
619 type(Pid, Type) -> ok | {error, Reason}
621 Types:
623 Pid = pid()
625 Type = ascii | binary
626 Reason = etype | restriction_reason() | common_reason()
627 Sets the file transfer type to ascii or binary. When an FTP ses‐
629 sion is opened, the default transfer type of the server is used,
630 most often ascii, which is default according to RFC 959.
631 user(Pid, User, Password) -> ok | {error, Reason}
633 Types:
635 Pid = pid()
637 User = Password = string()
638 Reason = euser | common_reason()
639 Performs login of User with Password.
641 user(Pid, User, Password, Account) -> ok | {error, Reason}
643 Types:
645 Pid = pid()
647 User = Password = string()
648 Reason = euser | common_reason()
649 Performs login of User with Password to the account specified by
651 Account.
652 quote(Pid, Command) -> [FTPLine]
654 Types:
656 Pid = pid()
658 Command = string()
659 FTPLine = string()
660 Note:
662 The telnet end of line characters, from the FTP protocol defini‐
663 tion, CRLF, for example, "\\r\\n" has been removed.
664 Sends an arbitrary FTP command and returns verbatim a list of
667 the lines sent back by the FTP server. This function is intended
668 to give application accesses to FTP commands that are server-
669 specific or that cannot be provided by this FTP client.
670 Note:
672 FTP commands requiring a data connection cannot be successfully
673 issued with this function.
674
677 The possible error reasons and the corresponding diagnostic strings re‐
678 turned by formaterror/1 are as follows:
679 echunk:
681 Synchronization error during chunk sending according to one of the
682 following:
683 * A call is made to send_chunk/2 or send_chunk_end/1 before a call
685 to send_chunk_start/2.
686 * A call has been made to another transfer function during chunk
688 sending, that is, before a call to send_chunk_end/1.
689 eclosed:
691 The session is closed.
692 econn:
694 Connection to the remote server is prematurely closed.
695 ehost:
697 Host is not found, FTP server is not found, or connection is re‐
698 jected by FTP server.
699 elogin:
701 User is not logged in.
702 enotbinary:
704 Term is not a binary.
705 epath:
707 No such file or directory, or directory already exists, or permis‐
708 sion denied.
709 etype:
711 No such type.
712 euser:
714 Invalid username or password.
715 etnospc:
717 Insufficient storage space in system [452].
718 epnospc:
720 Exceeded storage allocation (for current directory or dataset)
721 [552].
722 efnamena:
724 Filename not allowed [553].
725
727 file(3) filename(3) and J. Postel and J. Reynolds: File Transfer Proto‐
728 col (RFC 959).
729Ericsson AB ftp 1.1 ftp(3)