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 can be started in two ways. One is using the ser‐
17 vice_start function, the other is to start it directly as a standalone
18 process using function open.
19 For a simple example of an FTP session, see FTP User's Guide.
21 In addition to the ordinary functions for receiving and sending files
23 (see recv/2, recv/3, send/2, and send/3) there are functions for
24 receiving remote files as binaries (see recv_bin/2) and for sending
25 binaries to be stored as remote files (see send_bin/3).
26 A set of functions is provided for sending and receiving contiguous
28 parts of a file to be stored in a remote file. For send, see
29 send_chunk_start/2, send_chunk/2, and send_chunk_end/1. For receive,
30 see recv_chunk_start/2 and recv_chunk/).
31 The return values of the following functions depend much on the imple‐
33 mentation of the FTP server at the remote host. In particular, the
34 results from ls and nlist varies. Often real errors are not reported as
35 errors by ls, even if, for example, a file or directory does not exist.
36 nlist is usually more strict, but some implementations have the pecu‐
37 liar behaviour of responding with an error if the request is a listing
38 of the contents of a directory that exists but is empty.
39
41 The FTP client can be started and stopped dynamically in runtime by
42 calling the ftp application API ftp:start_service(ServiceConfig) and
43 ftp:stop_service(Pid).
44 The available configuration options are as follows:
46 {host, Host}:
48 Host = string() | ip_address()
51 {port, Port}:
53 Port = integer() > 0
56 Default is 21.
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
163 independent way. In this case the size becomes unknown and it is left
164 to 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 ASCCI 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
196 restrictions 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
224 appended 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
274 append_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()} | {timeout, timeout()}
398 | {dtimeout, dtimeout()} | {progress, progress() |
399 {sock_ctrl, sock_opts()} | {sock_data_act, sock_opts()} |
400 {sock_data_pass, sock_opts()} }
401 ipfamily() = inet | inet6 | inet6fb4 (default is inet)
402 port() = integer() > 0 (default is 21)
403 mode() = active | passive (default is passive)
404 tls_options() = [ssl:tls_option()]
405 sock_opts() = [gen_tcp:option() except for ipv6_v6only,
406 active, packet, mode, packet_size and header
407 timeout() = integer() > 0 (default is 60000 milliseconds)
408 dtimeout() = integer() > 0 | infinity (default is infinity)
409 pogress() = ignore | {module(), function(), initial_data()}
410 (default is ignore)
411 module() = atom()
412 function() = atom()
413 initial_data() = term()
414 Reason = ehost | term()
415 Starts a standalone FTP client process (without the ftp service
417 framework) and opens a session with the FTP server at Host.
418 If option {tls, tls_options()} is present, the FTP session is
420 transported over tls (ftps, see RFC 4217). The list
421 tls_options() can be empty. The function ssl:connect/3 is used
422 for securing both the control connection and the data sessions.
423 The options sock_ctrl, sock_data_act and sock_data_pass passes
425 options down to the underlying transport layer (tcp). The
426 default value for sock_ctrl is []. Both sock_data_act and
427 sock_data_pass uses the value of sock_ctrl as default value.
428 A session opened in this way is closed using function close.
430 pwd(Pid) -> {ok, Dir} | {error, Reason}
432 Types:
434 Pid = pid()
436 Reason = restriction_reason() | common_reason()
437 Returns the current working directory at the remote server.
439 recv(Pid, RemoteFile) ->
441 recv(Pid, RemoteFile, LocalFile) -> ok | {error, Reason}
442 Types:
444 Pid = pid()
446 RemoteFile = LocalFile = string()
447 Reason = restriction_reason() | common_reason() |
448 file_write_error_reason()
449 file_write_error_reason() = see file:write/2
450 Transfers the file RemoteFile from the remote server to the file
452 system of the local client. If LocalFile is specified, the local
453 file will be LocalFile, otherwise RemoteFile.
454 If the file write fails (for example, enospc), the command is
456 aborted and {error, file_write_error_reason()} is returned. How‐
457 ever, the file is not removed.
458 recv_bin(Pid, RemoteFile) -> {ok, Bin} | {error, Reason}
460 Types:
462 Pid = pid()
464 Bin = binary()
465 RemoteFile = string()
466 Reason = restriction_reason() | common_reason()
467 Transfers the file RemoteFile from the remote server and
469 receives it as a binary.
470 recv_chunk_start(Pid, RemoteFile) -> ok | {error, Reason}
472 Types:
474 Pid = pid()
476 RemoteFile = string()
477 Reason = restriction_reason() | common_reason()
478 Starts transfer of the file RemoteFile from the remote server.
480 recv_chunk(Pid) -> ok | {ok, Bin} | {error, Reason}
482 Types:
484 Pid = pid()
486 Bin = binary()
487 Reason = restriction_reason() | common_reason()
488 Receives a chunk of the remote file (RemoteFile of
490 recv_chunk_start). The return values have the following meaning:
491 * ok = the transfer is complete.
493 * {ok, Bin} = just another chunk of the file.
495 * {error, Reason} = transfer failed.
497 rename(Pid, Old, New) -> ok | {error, Reason}
499 Types:
501 Pid = pid()
503 CurrFile = NewFile = string()
504 Reason = restriction_reason() | common_reason()
505 Renames Old to New at the remote server.
507 rmdir(Pid, Dir) -> ok | {error, Reason}
509 Types:
511 Pid = pid()
513 Dir = string()
514 Reason = restriction_reason() | common_reason()
515 Removes directory Dir at the remote server.
517 send(Pid, LocalFile) ->
519 send(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}
520 Types:
522 Pid = pid()
524 LocalFile = RemoteFile = string()
525 Reason = restriction_reason() | common_reason() | short‐
526 age_reason()
527 Transfers the file LocalFile to the remote server. If RemoteFile
529 is specified, the name of the remote file is set to RemoteFile,
530 otherwise to LocalFile.
531 send_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}
533 Types:
535 Pid = pid()
537 Bin = binary()
538 RemoteFile = string()
539 Reason = restriction_reason() | common_reason() | short‐
540 age_reason()
541 Transfers the binary Bin into the file RemoteFile at the remote
543 server.
544 send_chunk(Pid, Bin) -> ok | {error, Reason}
546 Types:
548 Pid = pid()
550 Bin = binary()
551 Reason = echunk | restriction_reason() | common_reason()
552 Transfers the chunk Bin to the remote server, which writes it
554 into the file specified in the call to send_chunk_start/2.
555 For some errors, for example, file system full, it is necessary
557 to to call send_chunk_end to get the proper reason.
558 send_chunk_start(Pid, File) -> ok | {error, Reason}
560 Types:
562 Pid = pid()
564 File = string()
565 Reason = restriction_reason() | common_reason()
566 Starts transfer of chunks into the file File at the remote
568 server.
569 send_chunk_end(Pid) -> ok | {error, Reason}
571 Types:
573 Pid = pid()
575 Reason = restriction_reason() | common_reason() | short‐
576 age_reason()
577 Stops transfer of chunks to the remote server. The file at the
579 remote server, specified in the call to send_chunk_start/2 is
580 closed by the server.
581 start_service(ServiceConfig) -> {ok, Pid} | {error, Reason}
583 Types:
585 ServiceConfig = [{Option, Value}]
587 Option = property()
588 Value = term()
589 Dynamically starts an FTP session after the ftp application has
591 been started.
592 Note:
594 As long as the ftp application is operational, the FTP sessions
595 are supervised and can be soft code upgraded.
596 stop_service(Reference) -> ok | {error, Reason}
599 Types:
601 Reference = pid() | term() - service-specified reference
603 Reason = term()
604 Stops a started FTP session.
606 type(Pid, Type) -> ok | {error, Reason}
608 Types:
610 Pid = pid()
612 Type = ascii | binary
613 Reason = etype | restriction_reason() | common_reason()
614 Sets the file transfer type to ascii or binary. When an FTP ses‐
616 sion is opened, the default transfer type of the server is used,
617 most often ascii, which is default according to RFC 959.
618 user(Pid, User, Password) -> ok | {error, Reason}
620 Types:
622 Pid = pid()
624 User = Password = string()
625 Reason = euser | common_reason()
626 Performs login of User with Password.
628 user(Pid, User, Password, Account) -> ok | {error, Reason}
630 Types:
632 Pid = pid()
634 User = Password = string()
635 Reason = euser | common_reason()
636 Performs login of User with Password to the account specified by
638 Account.
639 quote(Pid, Command) -> [FTPLine]
641 Types:
643 Pid = pid()
645 Command = string()
646 FTPLine = string(
647 Note:
649 The telnet end of line characters, from the FTP protocol defini‐
650 tion, CRLF, for example, "\\r\\n" has been removed.
651 Sends an arbitrary FTP command and returns verbatim a list of
654 the lines sent back by the FTP server. This function is intended
655 to give application accesses to FTP commands that are server-
656 specific or that cannot be provided by this FTP client.
657 Note:
659 FTP commands requiring a data connection cannot be successfully
660 issued with this function.
661
664 The possible error reasons and the corresponding diagnostic strings
665 returned by formaterror/1 are as follows:
666 echunk:
668 Synchronization error during chunk sending according to one of the
669 following:
670 * A call is made to send_chunk/2 or send_chunk_end/1 before a call
672 to send_chunk_start/2.
673 * A call has been made to another transfer function during chunk
675 sending, that is, before a call to send_chunk_end/1.
676 eclosed:
678 The session is closed.
679 econn:
681 Connection to the remote server is prematurely closed.
682 ehost:
684 Host is not found, FTP server is not found, or connection is
685 rejected by FTP server.
686 elogin:
688 User is not logged in.
689 enotbinary:
691 Term is not a binary.
692 epath:
694 No such file or directory, or directory already exists, or permis‐
695 sion denied.
696 etype:
698 No such type.
699 euser:
701 Invalid username or password.
702 etnospc:
704 Insufficient storage space in system [452].
705 epnospc:
707 Exceeded storage allocation (for current directory or dataset)
708 [552].
709 efnamena:
711 Filename not allowed [553].
712
714 file(3) filename(3) and J. Postel and J. Reynolds: File Transfer Proto‐
715 col (RFC 959).
716Ericsson AB ftp 1.0.5 ftp(3)