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 As from Inets 4.4.1, the FTP client always tries to use passive FTP
13 mode and only resort to active FTP mode if this fails. This default
14 behavior can be changed by start option mode.
15 An FTP client can be started in two ways. One is using the Inets ser‐
17 vice framework, 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 Inets 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 provvided 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 Inets application API inets:start(ftpc, ServiceConfig), or
43 inets:start(ftpc, ServiceConfig, How), and inets:stop(ftpc, Pid). For
44 details, see inets(3).
45 The available configuration options are as follows:
47 {host, Host}:
49 Host = string() | ip_address()
52 {port, Port}:
54 Port = integer() > 0
57 Default is 21.
59 {mode, Mode}:
61 Mode = active | passive
64 Default is passive.
66 {verbose, Verbose}:
68 Verbose = boolean()
71 Determines if the FTP communication is to be verbose or not.
73 Default is false.
75 {debug, Debug}:
77 Debug = trace | debug | disable
80 Debugging using the dbg toolkit.
82 Default is disable.
84 {ipfamily, IpFamily}:
86 IpFamily = inet | inet6 | inet6fb4
89 With inet6fb4 the client behaves as before, that is, tries to use
91 IPv6, and only if that does not work it uses IPv4).
92 Default is inet (IPv4).
94 {timeout, Timeout}:
96 Timeout = non_neg_integer()
99 Connection time-out.
101 Default is 60000 (milliseconds).
103 {dtimeout, DTimeout}:
105 DTimeout = non_neg_integer() | infinity
108 Data connect time-out. The time the client waits for the server to
110 connect to the data socket.
111 Default is infinity.
113 {progress, Progress}:
115 Progress = ignore | {CBModule, CBFunction, InitProgress}
118 CBModule = atom(), CBFunction = atom()
120 InitProgress = term()
122 Default is ignore.
124 Option progress is intended to be used by applications that want to
126 create some type of progress report, such as a progress bar in a GUI.
127 Default for the progress option is ignore, that is, the option is not
128 used. When the progress option is specified, the following happens when
129 ftp:send/[3,4] or ftp:recv/[3,4] are called:
130 * Before a file is transferred, the following call is made to indi‐
132 cate the start of the file transfer and how large the file is. The
133 return value of the callback function is to be a new value for the
134 UserProgressTerm that will be used as input the next time the call‐
135 back function is called.
136 CBModule:CBFunction(InitProgress, File, {file_size, FileSize})
138 * Every time a chunk of bytes is transferred the following call is
140 made:
141 CBModule:CBFunction(UserProgressTerm, File, {transfer_size, Trans‐
143 ferSize})
144 * At the end of the file the following call is made to indicate the
146 end of the transfer:
147 CBModule:CBFunction(UserProgressTerm, File, {transfer_size, 0})
149 The callback function is to be defined as follows:
151 CBModule:CBFunction(UserProgressTerm, File, Size) -> UserProgressTerm
153 CBModule = CBFunction = atom()
155 UserProgressTerm = term()
157 File = string()
159 Size = {transfer_size, integer()} | {file_size, integer()} |
161 {file_size, unknown}
162 For remote files, ftp cannot determine the file size in a platform
164 independent way. In this case the size becomes unknown and it is left
165 to the application to determine the size.
166 Note:
168 The callback is made by a middleman process, hence the file transfer is
169 not affected by the code in the progress callback function. If the
170 callback crashes, this is detected by the FTP connection process, which
171 then prints an info-report and goes on as if the progress option was
172 set to ignore.
173 The file transfer type is set to the default of the FTP server when the
176 session is opened. This is usually ASCCI mode.
177 The current local working directory (compare lpwd/1) is set to the
179 value reported by file:get_cwd/1, the wanted local directory.
180 The return value Pid is used as a reference to the newly created FTP
182 client in all other functions, and they are to be called by the process
183 that created the connection. The FTP client process monitors the
184 process that created it and terminates if that process terminates.
185
187 The following type definitions are used by more than one function in
188 the FTP client API:
189 pid() = identifier of an FTP connection
191 string() = list of ASCII characters
193 shortage_reason() = etnospc | epnospc
195 restriction_reason() = epath | efnamena | elogin | enotbinary - all
197 restrictions are not always relevant to all functions
198 common_reason() = econn | eclosed | term() - some explanation of what
200 went wrong
201
203 account(Pid, Account) -> ok | {error, Reason}
204 Types:
206 Pid = pid()
208 Account = string()
209 Reason = eacct | common_reason()
210 Sets the account for an operation, if needed.
212 append(Pid, LocalFile) ->
214 append(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}
215 Types:
217 Pid = pid()
219 LocalFile = RemoteFile = string()
220 Reason = epath | elogin | etnospc | epnospc | efnamena | com‐
221 mon_reason
222 Transfers the file LocalFile to the remote server. If RemoteFile
224 is specified, the name of the remote file that the file is
225 appended to is set to RemoteFile, otherwise to LocalFile. If the
226 file does not exists, it is created.
227 append_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}
229 Types:
231 Pid = pid()
233 Bin = binary()()
234 RemoteFile = string()
235 Reason = restriction_reason()| shortage_reason() | com‐
236 mon_reason()
237 Transfers the binary Bin to the remote server and appends it to
239 the file RemoteFile. If the file does not exist, it is created.
240 append_chunk(Pid, Bin) -> ok | {error, Reason}
242 Types:
244 Pid = pid()
246 Bin = binary()
247 Reason = echunk | restriction_reason() | common_reason()
248 Transfers the chunk Bin to the remote server, which appends it
250 to the file specified in the call to append_chunk_start/2.
251 For some errors, for example, file system full, it is necessary
253 to call append_chunk_end to get the proper reason.
254 append_chunk_start(Pid, File) -> ok | {error, Reason}
256 Types:
258 Pid = pid()
260 File = string()
261 Reason = restriction_reason() | common_reason()
262 Starts the transfer of chunks for appending to the file File at
264 the remote server. If the file does not exist, it is created.
265 append_chunk_end(Pid) -> ok | {error, Reason}
267 Types:
269 Pid = pid()
271 Reason = echunk | restriction_reason() | shortage_reason()
272 Stops transfer of chunks for appending to the remote server. The
274 file at the remote server, specified in the call to
275 append_chunk_start/2, is closed by the server.
276 cd(Pid, Dir) -> ok | {error, Reason}
278 Types:
280 Pid = pid()
282 Dir = string()
283 Reason = restriction_reason() | common_reason()
284 Changes the working directory at the remote server to Dir.
286 close(Pid) -> ok
288 Types:
290 Pid = pid()
292 Ends an FTP session, created using function open.
294 delete(Pid, File) -> ok | {error, Reason}
296 Types:
298 Pid = pid()
300 File = string()
301 Reason = restriction_reason() | common_reason()
302 Deletes the file File at the remote server.
304 formaterror(Tag) -> string()
306 Types:
308 Tag = {error, atom()} | atom()
310 Given an error return value {error, AtomReason}, this function
312 returns a readable string describing the error.
313 lcd(Pid, Dir) -> ok | {error, Reason}
315 Types:
317 Pid = pid()
319 Dir = string()
320 Reason = restriction_reason()
321 Changes the working directory to Dir for the local client.
323 lpwd(Pid) -> {ok, Dir}
325 Types:
327 Pid = pid()
329 Returns the current working directory at the local client.
331 ls(Pid) ->
333 ls(Pid, Pathname) -> {ok, Listing} | {error, Reason}
334 Types:
336 Pid = pid()
338 Pathname = string()
339 Listing = string()
340 Reason = restriction_reason() | common_reason()
341 Returns a list of files in long format.
343 Pathname can be a directory, a group of files, or a file. The
345 Pathname string can contain wildcards.
346 ls/1 implies the current remote directory of the user.
348 The format of Listing depends on the operating system. On UNIX,
350 it is typically produced from the output of the ls -l shell com‐
351 mand.
352 mkdir(Pid, Dir) -> ok | {error, Reason}
354 Types:
356 Pid = pid()
358 Dir = string()
359 Reason = restriction_reason() | common_reason()
360 Creates the directory Dir at the remote server.
362 nlist(Pid) ->
364 nlist(Pid, Pathname) -> {ok, Listing} | {error, Reason}
365 Types:
367 Pid = pid()
369 Pathname = string()
370 Listing = string()
371 Reason = restriction_reason() | common_reason()
372 Returns a list of files in short format.
374 Pathname can be a directory, a group of files, or a file. The
376 Pathname string can contain wildcards.
377 nlist/1 implies the current remote directory of the user.
379 The format of Listing is a stream of filenames where each file‐
381 name is separated by <CRLF> or <NL>. Contrary to function ls,
382 the purpose of nlist is to enable a program to process filename
383 information automatically.
384 open(Host) -> {ok, Pid} | {error, Reason}
386 open(Host, Opts) -> {ok, Pid} | {error, Reason}
387 Types:
389 Host = string() | ip_address()
391 Opts = options()
392 options() = [option()]
393 option() = start_option() | open_option()
394 start_option() = {verbose, verbose()} | {debug, debug()}
395 verbose() = boolean() (default is false)
396 debug() = disable | debug | trace (default is disable)
397 open_option() = {ipfamily, ipfamily()} | {port, port()} |
398 {mode, mode()} | {tls, tls_options()} | {timeout, timeout()}
399 | {dtimeout, dtimeout()} | {progress, progress() |
400 {sock_ctrl, sock_opts()} | {sock_data_act, sock_opts()} |
401 {sock_data_pass, sock_opts()} }
402 ipfamily() = inet | inet6 | inet6fb4 (default is inet)
403 port() = integer() > 0 (default is 21)
404 mode() = active | passive (default is passive)
405 tls_options() = [ssl:ssloption()]
406 sock_opts() = [gen_tcp:option() except for ipv6_v6only,
407 active, packet, mode, packet_size and header
408 timeout() = integer() > 0 (default is 60000 milliseconds)
409 dtimeout() = integer() > 0 | infinity (default is infinity)
410 pogress() = ignore | {module(), function(), initial_data()}
411 (default is ignore)
412 module() = atom()
413 function() = atom()
414 initial_data() = term()
415 Reason = ehost | term()
416 Starts a standalone FTP client process (without the Inets ser‐
418 vice framework) and opens a session with the FTP server at Host.
419 If option {tls, tls_options()} is present, the FTP session is
421 transported over tls (ftps, see RFC 4217). The list
422 tls_options() can be empty. The function ssl:connect/3 is used
423 for securing both the control connection and the data sessions.
424 The options sock_ctrl, sock_data_act and sock_data_pass passes
426 options down to the underlying transport layer (tcp). The
427 default value for sock_ctrl is []. Both sock_data_act and
428 sock_data_pass uses the value of sock_ctrl as default value.
429 A session opened in this way is closed using function close.
431 pwd(Pid) -> {ok, Dir} | {error, Reason}
433 Types:
435 Pid = pid()
437 Reason = restriction_reason() | common_reason()
438 Returns the current working directory at the remote server.
440 recv(Pid, RemoteFile) ->
442 recv(Pid, RemoteFile, LocalFile) -> ok | {error, Reason}
443 Types:
445 Pid = pid()
447 RemoteFile = LocalFile = string()
448 Reason = restriction_reason() | common_reason() |
449 file_write_error_reason()
450 file_write_error_reason() = see file:write/2
451 Transfers the file RemoteFile from the remote server to the file
453 system of the local client. If LocalFile is specified, the local
454 file will be LocalFile, otherwise RemoteFile.
455 If the file write fails (for example, enospc), the command is
457 aborted and {error, file_write_error_reason()} is returned. How‐
458 ever, the file is not removed.
459 recv_bin(Pid, RemoteFile) -> {ok, Bin} | {error, Reason}
461 Types:
463 Pid = pid()
465 Bin = binary()
466 RemoteFile = string()
467 Reason = restriction_reason() | common_reason()
468 Transfers the file RemoteFile from the remote server and
470 receives it as a binary.
471 recv_chunk_start(Pid, RemoteFile) -> ok | {error, Reason}
473 Types:
475 Pid = pid()
477 RemoteFile = string()
478 Reason = restriction_reason() | common_reason()
479 Starts transfer of the file RemoteFile from the remote server.
481 recv_chunk(Pid) -> ok | {ok, Bin} | {error, Reason}
483 Types:
485 Pid = pid()
487 Bin = binary()
488 Reason = restriction_reason() | common_reason()
489 Receives a chunk of the remote file (RemoteFile of
491 recv_chunk_start). The return values have the following meaning:
492 * ok = the transfer is complete.
494 * {ok, Bin} = just another chunk of the file.
496 * {error, Reason} = transfer failed.
498 rename(Pid, Old, New) -> ok | {error, Reason}
500 Types:
502 Pid = pid()
504 CurrFile = NewFile = string()
505 Reason = restriction_reason() | common_reason()
506 Renames Old to New at the remote server.
508 rmdir(Pid, Dir) -> ok | {error, Reason}
510 Types:
512 Pid = pid()
514 Dir = string()
515 Reason = restriction_reason() | common_reason()
516 Removes directory Dir at the remote server.
518 send(Pid, LocalFile) ->
520 send(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}
521 Types:
523 Pid = pid()
525 LocalFile = RemoteFile = string()
526 Reason = restriction_reason() | common_reason() | short‐
527 age_reason()
528 Transfers the file LocalFile to the remote server. If RemoteFile
530 is specified, the name of the remote file is set to RemoteFile,
531 otherwise to LocalFile.
532 send_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}
534 Types:
536 Pid = pid()
538 Bin = binary()()
539 RemoteFile = string()
540 Reason = restriction_reason() | common_reason() | short‐
541 age_reason()
542 Transfers the binary Bin into the file RemoteFile at the remote
544 server.
545 send_chunk(Pid, Bin) -> ok | {error, Reason}
547 Types:
549 Pid = pid()
551 Bin = binary()
552 Reason = echunk | restriction_reason() | common_reason()
553 Transfers the chunk Bin to the remote server, which writes it
555 into the file specified in the call to send_chunk_start/2.
556 For some errors, for example, file system full, it is necessary
558 to to call send_chunk_end to get the proper reason.
559 send_chunk_start(Pid, File) -> ok | {error, Reason}
561 Types:
563 Pid = pid()
565 File = string()
566 Reason = restriction_reason() | common_reason()
567 Starts transfer of chunks into the file File at the remote
569 server.
570 send_chunk_end(Pid) -> ok | {error, Reason}
572 Types:
574 Pid = pid()
576 Reason = restriction_reason() | common_reason() | short‐
577 age_reason()
578 Stops transfer of chunks to the remote server. The file at the
580 remote server, specified in the call to send_chunk_start/2 is
581 closed by the server.
582 type(Pid, Type) -> ok | {error, Reason}
584 Types:
586 Pid = pid()
588 Type = ascii | binary
589 Reason = etype | restriction_reason() | common_reason()
590 Sets the file transfer type to ascii or binary. When an FTP ses‐
592 sion is opened, the default transfer type of the server is used,
593 most often ascii, which is default according to RFC 959.
594 user(Pid, User, Password) -> ok | {error, Reason}
596 Types:
598 Pid = pid()
600 User = Password = string()
601 Reason = euser | common_reason()
602 Performs login of User with Password.
604 user(Pid, User, Password, Account) -> ok | {error, Reason}
606 Types:
608 Pid = pid()
610 User = Password = string()
611 Reason = euser | common_reason()
612 Performs login of User with Password to the account specified by
614 Account.
615 quote(Pid, Command) -> [FTPLine]
617 Types:
619 Pid = pid()
621 Command = string()
622 FTPLine = string(
623 Note:
625 The telnet end of line characters, from the FTP protocol defini‐
626 tion, CRLF, for example, "\\r\\n" has been removed.
627 Sends an arbitrary FTP command and returns verbatim a list of
630 the lines sent back by the FTP server. This function is intended
631 to give application accesses to FTP commands that are server-
632 specific or that cannot be provided by this FTP client.
633 Note:
635 FTP commands requiring a data connection cannot be successfully
636 issued with this function.
637
640 The possible error reasons and the corresponding diagnostic strings
641 returned by formaterror/1 are as follows:
642 echunk:
644 Synchronization error during chunk sending according to one of the
645 following:
646 * A call is made to send_chunk/2 or send_chunk_end/1 before a call
648 to send_chunk_start/2.
649 * A call has been made to another transfer function during chunk
651 sending, that is, before a call to send_chunk_end/1.
652 eclosed:
654 The session is closed.
655 econn:
657 Connection to the remote server is prematurely closed.
658 ehost:
660 Host is not found, FTP server is not found, or connection is
661 rejected by FTP server.
662 elogin:
664 User is not logged in.
665 enotbinary:
667 Term is not a binary.
668 epath:
670 No such file or directory, or directory already exists, or permis‐
671 sion denied.
672 etype:
674 No such type.
675 euser:
677 Invalid username or password.
678 etnospc:
680 Insufficient storage space in system [452].
681 epnospc:
683 Exceeded storage allocation (for current directory or dataset)
684 [552].
685 efnamena:
687 Filename not allowed [553].
688
690 file(3) filename(3) and J. Postel and J. Reynolds: File Transfer Proto‐
691 col (RFC 959).
692Ericsson AB inets 6.5.2.4 ftp(3)