ftp(3erl)

1ftp(3)                     Erlang Module Definition                     ftp(3)
2
3
4

NAME

6       ftp - A File Transfer Protocol client.
7

DESCRIPTION

9       This module implements a client for file transfer according to a subset
10       of the File Transfer Protocol (FTP), see RFC 959.
11
12       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
16       An FTP client is always started as part  of  the  ftp  application  and
17       legacy start_service function, is deprecated in OTP-24
18
19       For a simple example of an FTP session, see FTP User's Guide.
20
21       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
26       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
31       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

FTP CLIENT START/STOP

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
44       The available configuration options are as follows:
45
46         {host, Host}:
47
48
49           Host = string() | ip_address()
50
51         {port, Port}:
52
53
54           Port = integer() > 0
55
56           Default   is   0  which  aliases  to  21  or  990  when  used  with
57           {tls_sec_method,ftps}).
58
59         {mode, Mode}:
60
61
62           Mode = active | passive
63
64           Default is passive.
65
66         {verbose, Verbose}:
67
68
69           Verbose = boolean()
70
71           Determines if the FTP communication is to be verbose or not.
72
73           Default is false.
74
75         {debug, Debug}:
76
77
78           Debug = trace | debug | disable
79
80           Debugging using the dbg toolkit.
81
82           Default is disable.
83
84         {ipfamily, IpFamily}:
85
86
87           IpFamily = inet | inet6 | inet6fb4
88
89           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
92           Default is inet (IPv4).
93
94         {timeout, Timeout}:
95
96
97           Timeout = non_neg_integer()
98
99           Connection time-out.
100
101           Default is 60000 (milliseconds).
102
103         {dtimeout, DTimeout}:
104
105
106           DTimeout = non_neg_integer() | infinity
107
108           Data  connect time-out. The time the client waits for the server to
109           connect to the data socket.
110
111           Default is infinity.
112
113         {progress, Progress}:
114
115
116           Progress = ignore | {CBModule, CBFunction, InitProgress}
117
118           CBModule = atom(), CBFunction = atom()
119
120           InitProgress = term()
121
122           Default is ignore.
123
124       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
130         * 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
136            CBModule:CBFunction(InitProgress, File, {file_size, FileSize})
137
138         * Every time a chunk of bytes is transferred the  following  call  is
139           made:
140
141            CBModule:CBFunction(UserProgressTerm, File, {transfer_size, Trans‐
142           ferSize})
143
144         * At the end of the file the following call is made to  indicate  the
145           end of the transfer:
146
147            CBModule:CBFunction(UserProgressTerm, File, {transfer_size, 0})
148
149       The callback function is to be defined as follows:
150
151        CBModule:CBFunction(UserProgressTerm, File, Size) -> UserProgressTerm
152
153        CBModule = CBFunction = atom()
154
155        UserProgressTerm = term()
156
157        File = string()
158
159        Size   =   {transfer_size,   integer()}  |  {file_size,  integer()}  |
160       {file_size, unknown}
161
162       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
166   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
173
174       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
177       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
180       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

DATA TYPES

186       The  following  type  definitions are used by more than one function in
187       the FTP client API:
188
189       pid() = identifier of an FTP connection
190
191       string() = list of ASCII characters
192
193       shortage_reason() = etnospc | epnospc
194
195       restriction_reason() = epath | efnamena | elogin | enotbinary - all re‐
196       strictions are not always relevant to all functions
197
198       common_reason()  =  econn | eclosed | term() - some explanation of what
199       went wrong
200

EXPORTS

202       account(Pid, Account) -> ok | {error, Reason}
203
204              Types:
205
206                 Pid = pid()
207                 Account = string()
208                 Reason = eacct | common_reason()
209
210              Sets the account for an operation, if needed.
211
212       append(Pid, LocalFile) ->
213       append(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}
214
215              Types:
216
217                 Pid = pid()
218                 LocalFile = RemoteFile = string()
219                 Reason = epath | elogin | etnospc | epnospc | efnamena | com‐
220                 mon_reason
221
222              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
227       append_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}
228
229              Types:
230
231                 Pid = pid()
232                 Bin = binary()
233                 RemoteFile = string()
234                 Reason  =  restriction_reason()|  shortage_reason()  |   com‐
235                 mon_reason()
236
237              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
240       append_chunk(Pid, Bin) -> ok | {error, Reason}
241
242              Types:
243
244                 Pid = pid()
245                 Bin = binary()
246                 Reason = echunk | restriction_reason() | common_reason()
247
248              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
251              For  some errors, for example, file system full, it is necessary
252              to call append_chunk_end to get the proper reason.
253
254       append_chunk_start(Pid, File) -> ok | {error, Reason}
255
256              Types:
257
258                 Pid = pid()
259                 File = string()
260                 Reason = restriction_reason() | common_reason()
261
262              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
265       append_chunk_end(Pid) -> ok | {error, Reason}
266
267              Types:
268
269                 Pid = pid()
270                 Reason = echunk | restriction_reason() | shortage_reason()
271
272              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
276       cd(Pid, Dir) -> ok | {error, Reason}
277
278              Types:
279
280                 Pid = pid()
281                 Dir = string()
282                 Reason = restriction_reason() | common_reason()
283
284              Changes the working directory at the remote server to Dir.
285
286       close(Pid) -> ok
287
288              Types:
289
290                 Pid = pid()
291
292              Ends an FTP session, created using function open.
293
294       delete(Pid, File) -> ok | {error, Reason}
295
296              Types:
297
298                 Pid = pid()
299                 File = string()
300                 Reason = restriction_reason() | common_reason()
301
302              Deletes the file File at the remote server.
303
304       formaterror(Tag) -> string()
305
306              Types:
307
308                 Tag = {error, atom()} | atom()
309
310              Given  an  error return value {error, AtomReason}, this function
311              returns a readable string describing the error.
312
313       lcd(Pid, Dir) -> ok | {error, Reason}
314
315              Types:
316
317                 Pid = pid()
318                 Dir = string()
319                 Reason = restriction_reason()
320
321              Changes the working directory to Dir for the local client.
322
323       lpwd(Pid) -> {ok, Dir}
324
325              Types:
326
327                 Pid = pid()
328
329              Returns the current working directory at the local client.
330
331       ls(Pid) ->
332       ls(Pid, Pathname) -> {ok, Listing} | {error, Reason}
333
334              Types:
335
336                 Pid = pid()
337                 Pathname = string()
338                 Listing = string()
339                 Reason = restriction_reason() | common_reason()
340
341              Returns a list of files in long format.
342
343              Pathname can be a directory, a group of files, or  a  file.  The
344              Pathname string can contain wildcards.
345
346              ls/1 implies the current remote directory of the user.
347
348              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
352       mkdir(Pid, Dir) -> ok | {error, Reason}
353
354              Types:
355
356                 Pid = pid()
357                 Dir = string()
358                 Reason = restriction_reason() | common_reason()
359
360              Creates the directory Dir at the remote server.
361
362       nlist(Pid) ->
363       nlist(Pid, Pathname) -> {ok, Listing} | {error, Reason}
364
365              Types:
366
367                 Pid = pid()
368                 Pathname = string()
369                 Listing = string()
370                 Reason = restriction_reason() | common_reason()
371
372              Returns a list of files in short format.
373
374              Pathname  can  be  a directory, a group of files, or a file. The
375              Pathname string can contain wildcards.
376
377              nlist/1 implies the current remote directory of the user.
378
379              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
384       open(Host) -> {ok, Pid} | {error, Reason}
385       open(Host, Opts) -> {ok, Pid} | {error, Reason}
386
387              Types:
388
389                 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
419              Starts  a  FTP  client  process and opens a session with the FTP
420              server at Host.
421
422              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
427              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
432              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
437              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
442              A session opened in this way is closed using function close.
443
444       pwd(Pid) -> {ok, Dir} | {error, Reason}
445
446              Types:
447
448                 Pid = pid()
449                 Reason = restriction_reason() | common_reason()
450
451              Returns the current working directory at the remote server.
452
453       recv(Pid, RemoteFile) ->
454       recv(Pid, RemoteFile, LocalFile) -> ok | {error, Reason}
455
456              Types:
457
458                 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
464              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
468              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
472       recv_bin(Pid, RemoteFile) -> {ok, Bin} | {error, Reason}
473
474              Types:
475
476                 Pid = pid()
477                 Bin = binary()
478                 RemoteFile = string()
479                 Reason = restriction_reason() | common_reason()
480
481              Transfers  the  file  RemoteFile  from the remote server and re‐
482              ceives it as a binary.
483
484       recv_chunk_start(Pid, RemoteFile) -> ok | {error, Reason}
485
486              Types:
487
488                 Pid = pid()
489                 RemoteFile = string()
490                 Reason = restriction_reason() | common_reason()
491
492              Starts transfer of the file RemoteFile from the remote server.
493
494       recv_chunk(Pid) -> ok | {ok, Bin} | {error, Reason}
495
496              Types:
497
498                 Pid = pid()
499                 Bin = binary()
500                 Reason = restriction_reason() | common_reason()
501
502              Receives  a  chunk   of   the   remote   file   (RemoteFile   of
503              recv_chunk_start). The return values have the following meaning:
504
505                * ok = the transfer is complete.
506
507                * {ok, Bin} = just another chunk of the file.
508
509                * {error, Reason} = transfer failed.
510
511       rename(Pid, Old, New) -> ok | {error, Reason}
512
513              Types:
514
515                 Pid = pid()
516                 CurrFile = NewFile = string()
517                 Reason = restriction_reason() | common_reason()
518
519              Renames Old to New at the remote server.
520
521       rmdir(Pid, Dir) -> ok | {error, Reason}
522
523              Types:
524
525                 Pid = pid()
526                 Dir = string()
527                 Reason = restriction_reason() | common_reason()
528
529              Removes directory Dir at the remote server.
530
531       send(Pid, LocalFile) ->
532       send(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}
533
534              Types:
535
536                 Pid = pid()
537                 LocalFile = RemoteFile = string()
538                 Reason  =  restriction_reason()  |  common_reason()  | short‐
539                 age_reason()
540
541              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
545       send_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}
546
547              Types:
548
549                 Pid = pid()
550                 Bin = binary()
551                 RemoteFile = string()
552                 Reason =  restriction_reason()  |  common_reason()  |  short‐
553                 age_reason()
554
555              Transfers  the binary Bin into the file RemoteFile at the remote
556              server.
557
558       send_chunk(Pid, Bin) -> ok | {error, Reason}
559
560              Types:
561
562                 Pid = pid()
563                 Bin = binary()
564                 Reason = echunk | restriction_reason() | common_reason()
565
566              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
569              For  some errors, for example, file system full, it is necessary
570              to to call send_chunk_end to get the proper reason.
571
572       send_chunk_start(Pid, File) -> ok | {error, Reason}
573
574              Types:
575
576                 Pid = pid()
577                 File = string()
578                 Reason = restriction_reason() | common_reason()
579
580              Starts transfer of chunks into  the  file  File  at  the  remote
581              server.
582
583       send_chunk_end(Pid) -> ok | {error, Reason}
584
585              Types:
586
587                 Pid = pid()
588                 Reason  =  restriction_reason()  |  common_reason()  | short‐
589                 age_reason()
590
591              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
595       start_service(ServiceConfig) -> {ok, Pid} | {error, Reason}
596
597              Types:
598
599                 ServiceConfig = [{Option, Value}]
600                 Option = property()
601                 Value = term()
602
603              Dynamically starts an FTP session after the ftp application  has
604              been started.
605
606          Note:
607              As  long as the ftp application is operational, the FTP sessions
608              are supervised and can be soft code upgraded.
609
610
611       stop_service(Reference) -> ok | {error, Reason}
612
613              Types:
614
615                 Reference = pid() | term() - service-specified reference
616                 Reason = term()
617
618              Stops a started FTP session.
619
620       type(Pid, Type) -> ok | {error, Reason}
621
622              Types:
623
624                 Pid = pid()
625                 Type = ascii | binary
626                 Reason = etype | restriction_reason() | common_reason()
627
628              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
632       user(Pid, User, Password) -> ok | {error, Reason}
633
634              Types:
635
636                 Pid = pid()
637                 User = Password = string()
638                 Reason = euser | common_reason()
639
640              Performs login of User with Password.
641
642       user(Pid, User, Password, Account) -> ok | {error, Reason}
643
644              Types:
645
646                 Pid = pid()
647                 User = Password = string()
648                 Reason = euser | common_reason()
649
650              Performs login of User with Password to the account specified by
651              Account.
652
653       quote(Pid, Command) -> [FTPLine]
654
655              Types:
656
657                 Pid = pid()
658                 Command = string()
659                 FTPLine = string()
660
661          Note:
662              The telnet end of line characters, from the FTP protocol defini‐
663              tion, CRLF, for example, "\\r\\n" has been removed.
664
665
666              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
671          Note:
672              FTP  commands requiring a data connection cannot be successfully
673              issued with this function.
674
675

ERRORS

677       The possible error reasons and the corresponding diagnostic strings re‐
678       turned by formaterror/1 are as follows:
679
680         echunk:
681           Synchronization  error during chunk sending according to one of the
682           following:
683
684           * A call is made to send_chunk/2 or send_chunk_end/1 before a  call
685             to send_chunk_start/2.
686
687           * A  call  has  been made to another transfer function during chunk
688             sending, that is, before a call to send_chunk_end/1.
689
690         eclosed:
691           The session is closed.
692
693         econn:
694           Connection to the remote server is prematurely closed.
695
696         ehost:
697           Host is not found, FTP server is not found, or  connection  is  re‐
698           jected by FTP server.
699
700         elogin:
701           User is not logged in.
702
703         enotbinary:
704           Term is not a binary.
705
706         epath:
707           No  such file or directory, or directory already exists, or permis‐
708           sion denied.
709
710         etype:
711           No such type.
712
713         euser:
714           Invalid username or password.
715
716         etnospc:
717           Insufficient storage space in system [452].
718
719         epnospc:
720           Exceeded storage allocation  (for  current  directory  or  dataset)
721           [552].
722
723         efnamena:
724           Filename not allowed [553].
725

NAME

DESCRIPTION

FTP CLIENT START/STOP

DATA TYPES

EXPORTS

ERRORS

SEE ALSO