1ftp(3) Erlang Module Definition ftp(3)
2
3
4
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
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 For a simple example of an FTP session, see FTP User's Guide.
17
18 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
23 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
28 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
45 pid() = identifier of an FTP connection
46
47 string() = list of ASCII characters
48
50 account(Pid :: pid(), Acc :: string()) ->
51 ok | {error, Reason :: term()}
52
53 Sets the account for an operation, if needed.
54
55 append(Pid :: pid(), LocalFileName :: string()) ->
56 ok | {error, Reason :: term()}
57
58 append(Pid :: pid(),
59 LocalFileName :: string(),
60 RemoteFileName :: string()) ->
61 ok | {error, Reason :: term()}
62
63 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
68 append_bin(Pid :: pid(), Bin :: binary(), RemoteFile :: string()) ->
69 ok | {error, Reason :: term()}
70
71 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
74 append_chunk(Pid :: pid(), Bin :: binary()) ->
75 ok | {error, Reason :: term()}
76
77 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
80 For some errors, for example, file system full, it is necessary
81 to call append_chunk_end to get the proper reason.
82
83 append_chunk_start(Pid :: pid(), RemoteFile :: string()) ->
84 ok | {error, Reason :: term()}
85
86 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
90 append_chunk_end(Pid :: pid()) -> ok | {error, Reason :: term()}
91
92 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
96 cd(Pid :: pid(), Dir :: string()) ->
97 ok | {error, Reason :: term()}
98
99 Changes the working directory at the remote server to Dir.
100
101 close(Pid :: pid()) -> ok
102
103 Ends an FTP session, created using function open.
104
105 delete(Pid :: pid(), File :: string()) ->
106 ok | {error, Reason :: term()}
107
108 Deletes the file File at the remote server.
109
110 formaterror(Tag :: atom() | {error, atom()}) -> string()
111
112 Given an error return value {error, AtomReason}, this function
113 returns a readable string describing the error.
114
115 lcd(Pid :: pid(), Dir :: string()) ->
116 ok | {error, Reason :: term()}
117
118 Changes the working directory to Dir for the local client.
119
120 lpwd(Pid :: pid()) -> {ok, Dir :: string()}
121
122 Returns the current working directory at the local client.
123
124 ls(Pid :: pid()) ->
125 {ok, Listing :: string()} | {error, Reason :: term()}
126
127 ls(Pid :: pid(), Dir :: string()) ->
128 {ok, Listing :: string()} | {error, Reason :: term()}
129
130 Returns a list of files in long format.
131
132 Dir can be a directory or a file. The Dir string can contain
133 wildcards.
134
135 ls/1 implies the current remote directory of the user.
136
137 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
141 mkdir(Pid :: pid(), Dir :: string()) ->
142 ok | {error, Reason :: term()}
143
144 Creates the directory Dir at the remote server.
145
146 nlist(Pid :: pid()) ->
147 {ok, Listing :: string()} | {error, Reason :: term()}
148
149 nlist(Pid :: pid(), Pathname :: string()) ->
150 {ok, Listing :: string()} | {error, Reason :: term()}
151
152 Returns a list of files in short format.
153
154 Pathname can be a directory or a file. The Pathname string can
155 contain wildcards.
156
157 nlist/1 implies the current remote directory of the user.
158
159 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
164 open(Host :: string() | inet:ip_address()) ->
165 {ok, Pid :: pid()} | {error, Reason :: term()}
166
167 open(Host :: string() | inet:ip_address(), Opts) ->
168 {ok, Pid :: pid()} | {error, Reason :: term()}
169
170 Types:
171
172 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
198 Starts a FTP client process and opens a session with the FTP
199 server at Host.
200
201 A session opened in this way is closed using function close.
202
203 The available configuration options are as follows:
204
205 {host, Host}:
206
207
208 Host = string() | ip_address()
209
210 {port, Port}:
211
212
213 Default is 0 which aliases to 21 or 990 when used with
214 {tls_sec_method,ftps}).
215
216 {mode, Mode}:
217
218
219 Default is passive.
220
221 {verbose, Verbose}:
222
223
224 Determines if the FTP communication is to be verbose or not.
225
226 Default is false.
227
228 {debug, Debug}:
229
230
231 Debugging using the dbg toolkit.
232
233 Default is disable.
234
235 {ipfamily, IpFamily}:
236
237
238 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
241 Default is inet (IPv4).
242
243 {timeout, Timeout}:
244
245
246 Connection time-out.
247
248 Default is 60000 (milliseconds).
249
250 {dtimeout, DTimeout}:
251
252
253 Data connect time-out. The time the client waits for the
254 server to connect to the data socket.
255
256 Default is infinity.
257
258 {tls, TLSOptions}:
259
260
261 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
266 {tls_sec_method, TLSSecMethod}:
267
268
269 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
273 Default is ftpes
274
275 {tls_ctrl_session_reuse, boolean()}:
276
277
278 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
282 Default is false.
283
284 {sock_ctrl, SocketCtrls :: [SocketControl :: gen_tcp:op‐
285 tion()]}:
286 Passes options from SocketCtrls down to the underlying
287 transport layer (tcp).
288
289 gen_tcp:option() except for ipv6_v6only, active, packet,
290 mode, packet_size and header.
291
292 Default value is SocketCtrls = [].
293
294 {sock_data_act, [SocketControl]}:
295 Passes options from [SocketControl] down to the underlying
296 transport layer (tcp).
297
298 sock_data_act uses the value of sock_ctrl as default value.
299
300 {sock_data_pass, [SocketControl]}:
301 Passes options from [SocketControl] down to the underlying
302 transport layer (tcp).
303
304 sock_data_pass uses the value of sock_ctrl as default value.
305
306 {progress, Progress}:
307
308
309 Progress = ignore | {Module, Function, InitialData}
310
311 Module = atom(), Function = atom()
312
313 InitialData = term()
314
315 Default is ignore.
316
317 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
324 * 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
331 Module:Function(InitialData, File, {file_size, FileSize})
332
333
334 * Every time a chunk of bytes is transferred the following
335 call is made:
336
337 Module:Function(UserProgressTerm, File, {transfer_size,
338 TransferSize})
339
340 * At the end of the file the following call is made to indi‐
341 cate the end of the transfer:
342
343 Module:Function(UserProgressTerm, File, {transfer_size,
344 0})
345
346 The callback function is to be defined as follows:
347
348 Module:Function(UserProgressTerm, File, Size) -> UserPro‐
349 gressTerm
350
351 UserProgressTerm = term()
352
353 File = string()
354
355 Size = {transfer_size, integer()} | {file_size, integer()}
356 | {file_size, unknown}
357
358 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
363 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
370
371 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
375 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
379 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
385 pwd(Pid :: pid()) ->
386 {ok, Dir :: string()} | {error, Reason :: term()}
387
388 Returns the current working directory at the remote server.
389
390 recv(Pid :: pid(), RemoteFileName :: string()) ->
391 ok | {error, Reason :: term()}
392
393 recv(Pid :: pid(),
394 RemoteFileName :: string(),
395 LocalFileName :: string()) ->
396 ok | {error, Reason :: term()}
397
398 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
402 If the file write fails, the command is aborted and {error,
403 term()} is returned. However, the file is not removed.
404
405 recv_bin(Pid :: pid(), RemoteFile :: string()) ->
406 {ok, Bin :: binary()} | {error, Reason :: term()}
407
408 Transfers the file RemoteFile from the remote server and re‐
409 ceives it as a binary.
410
411 recv_chunk_start(Pid :: pid(), RemoteFile :: string()) ->
412 ok | {error, Reason :: term()}
413
414 Starts transfer of the file RemoteFile from the remote server.
415
416 recv_chunk(Pid :: pid()) ->
417 ok |
418 {ok, Bin :: binary()} |
419 {error, Reason :: term()}
420
421 Receives a chunk of the remote file (RemoteFile of
422 recv_chunk_start). The return values have the following meaning:
423
424 * ok = the transfer is complete.
425
426 * {ok, Bin} = just another chunk of the file.
427
428 * {error, Reason} = transfer failed.
429
430 rename(Pid :: pid(), Old :: string(), New :: string()) ->
431 ok | {error, Reason :: term()}
432
433 Renames Old to New at the remote server.
434
435 rmdir(Pid :: pid(), Dir :: string()) ->
436 ok | {error, Reason :: term()}
437
438 Removes directory Dir at the remote server.
439
440 send(Pid :: pid(), LocalFileName :: string()) ->
441 ok | {error, Reason :: term()}
442
443 send(Pid :: pid(),
444 LocalFileName :: string(),
445 RemoteFileName :: string()) ->
446 ok | {error, Reason :: term()}
447
448 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
452 send_bin(Pid :: pid(), Bin :: binary(), RemoteFile :: string()) ->
453 ok | {error, Reason :: term()}
454
455 Transfers the binary Bin into the file RemoteFile at the remote
456 server.
457
458 send_chunk(Pid :: pid(), Bin :: binary()) ->
459 ok | {error, Reason :: term()}
460
461 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
464 For some errors, for example, file system full, it is necessary
465 to to call send_chunk_end to get the proper reason.
466
467 send_chunk_start(Pid :: pid(), RemoteFile :: string()) ->
468 ok | {error, Reason :: term()}
469
470 Starts transfer of chunks into the file RemoteFile at the remote
471 server.
472
473 send_chunk_end(Pid :: pid()) -> ok | {error, Reason :: term()}
474
475 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
479 type(Pid :: pid(), Type :: ascii | binary) ->
480 ok | {error, Reason :: term()}
481
482 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
486 user(Pid :: pid(), User :: string(), Pass :: string()) ->
487 ok | {error, Reason :: term()}
488
489 Performs login of User with Pass.
490
491 user(Pid :: pid(),
492 User :: string(),
493 Pass :: string(),
494 Account :: string()) ->
495 ok | {error, Reason :: term()}
496
497 Performs login of User with Pass to the account specified by Ac‐
498 count.
499
500 quote(Pid :: pid(), Cmd :: string()) -> [FTPLine :: string()]
501
502 Note:
503 The telnet end of line characters, from the FTP protocol defini‐
504 tion, CRLF, for example, "\\r\\n" has been removed.
505
506
507 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
512 Note:
513 FTP commands requiring a data connection cannot be successfully
514 issued with this function.
515
516
518 The possible error reasons and the corresponding diagnostic strings re‐
519 turned by formaterror/1 are as follows:
520
521 echunk:
522 Synchronization error during chunk sending according to one of the
523 following:
524
525 * A call is made to send_chunk/2 or send_chunk_end/1 before a call
526 to send_chunk_start/2.
527
528 * A call has been made to another transfer function during chunk
529 sending, that is, before a call to send_chunk_end/1.
530
531 eclosed:
532 The session is closed.
533
534 econn:
535 Connection to the remote server is prematurely closed.
536
537 ehost:
538 Host is not found, FTP server is not found, or connection is re‐
539 jected by FTP server.
540
541 elogin:
542 User is not logged in.
543
544 enotbinary:
545 Term is not a binary.
546
547 epath:
548 No such file or directory, or directory already exists, or permis‐
549 sion denied.
550
551 etype:
552 No such type.
553
554 euser:
555 Invalid username or password.
556
557 etnospc:
558 Insufficient storage space in system [452].
559
560 epnospc:
561 Exceeded storage allocation (for current directory or dataset)
562 [552].
563
564 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).
570
571
572
573Ericsson AB ftp 1.2 ftp(3)