A File Transfer Protocol client.
This module implements a client for file transfer according to a subset of the File Transfer Protocol (FTP), see RFC 959
.
The FTP client always tries to use passive FTP mode and only resort to active FTP mode if this fails. This default behavior can be changed by start option mode
.
A set of functions is provvided for sending and receiving contiguous parts of a file to be stored in a remote file. For send, see send_chunk_start/2
, send_chunk/2
, and send_chunk_end/1
. For receive, see recv_chunk_start/2
and recv_chunk/
).
The return values of the following functions depend much on the implementation of the FTP server at the remote host. In particular, the results from ls
and nlist
varies. Often real errors are not reported as errors by ls
, even if, for example, a file or directory does not exist. nlist
is usually more strict, but some implementations have the peculiar behaviour of responding with an error if the request is a listing of the contents of a directory that exists but is empty.
The file transfer type is set to the default of the FTP server when the session is opened. This is usually ASCCI mode.
The following type definitions are used by more than one function in the FTP client API:
account(Pid, Account) -> ok | {error, Reason}
Types
Sets the account for an operation, if needed.
append(Pid, LocalFile) ->
append(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}
Types
Transfers the file LocalFile
to the remote server. If RemoteFile
is specified, the name of the remote file that the file is appended to is set to RemoteFile
, otherwise to LocalFile
. If the file does not exists, it is created.
append_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}
Types
Transfers the binary Bin
to the remote server and appends it to the file RemoteFile
. If the file does not exist, it is created.
append_chunk(Pid, Bin) -> ok | {error, Reason}
Types
Transfers the chunk Bin
to the remote server, which appends it to the file specified in the call to append_chunk_start/2
.
For some errors, for example, file system full, it is necessary to call append_chunk_end
to get the proper reason.
append_chunk_start(Pid, File) -> ok | {error, Reason}
Types
Starts the transfer of chunks for appending to the file File
at the remote server. If the file does not exist, it is created.
append_chunk_end(Pid) -> ok | {error, Reason}
Types
Stops transfer of chunks for appending to the remote server. The file at the remote server, specified in the call to append_chunk_start/2
, is closed by the server.
cd(Pid, Dir) -> ok | {error, Reason}
Types
Changes the working directory at the remote server to Dir
.
close(Pid) -> ok
Types
Ends an FTP session, created using function open
.
delete(Pid, File) -> ok | {error, Reason}
Types
Deletes the file File
at the remote server.
formaterror(Tag) -> string()
Types
Given an error return value {error, AtomReason}
, this function returns a readable string describing the error.
lcd(Pid, Dir) -> ok | {error, Reason}
Types
Changes the working directory to Dir
for the local client.
lpwd(Pid) -> {ok, Dir}
Types
Returns the current working directory at the local client.
ls(Pid) ->
ls(Pid, Pathname) -> {ok, Listing} | {error, Reason}
Types
Returns a list of files in long format.
Pathname
can be a directory, a group of files, or a file. The Pathname
string can contain wildcards.
ls/1
implies the current remote directory of the user.
The format of Listing
depends on the operating system. On UNIX, it is typically produced from the output of the ls -l
shell command.
mkdir(Pid, Dir) -> ok | {error, Reason}
Types
Creates the directory Dir
at the remote server.
nlist(Pid) ->
nlist(Pid, Pathname) -> {ok, Listing} | {error, Reason}
Types
Returns a list of files in short format.
Pathname
can be a directory, a group of files, or a file. The Pathname
string can contain wildcards.
nlist/1
implies the current remote directory of the user.
The format of Listing
is a stream of filenames where each filename is separated by <CRLF> or <NL>. Contrary to function ls
, the purpose of nlist
is to enable a program to process filename information automatically.
open(Host) -> {ok, Pid} | {error, Reason}
open(Host, Opts) -> {ok, Pid} | {error, Reason}
Types
Starts a standalone FTP client process (without the ftp
service framework) and opens a session with the FTP server at Host
.
If option {tls, tls_options()}
is present, the FTP session is transported over tls
(ftps
, see RFC 4217
). The list tls_options()
can be empty. The function ssl:connect/3
is used for securing both the control connection and the data sessions.
A session opened in this way is closed using function close
.
pwd(Pid) -> {ok, Dir} | {error, Reason}
Types
Returns the current working directory at the remote server.
recv(Pid, RemoteFile) ->
recv(Pid, RemoteFile, LocalFile) -> ok | {error, Reason}
Types
Transfers the file RemoteFile
from the remote server to the file system of the local client. If LocalFile
is specified, the local file will be LocalFile
, otherwise RemoteFile
.
If the file write fails (for example, enospc
), the command is aborted and {error, file_write_error_reason()}
is returned. However, the file is not removed.
recv_bin(Pid, RemoteFile) -> {ok, Bin} | {error, Reason}
Types
Transfers the file RemoteFile
from the remote server and receives it as a binary.
recv_chunk_start(Pid, RemoteFile) -> ok | {error, Reason}
Types
Starts transfer of the file RemoteFile
from the remote server.
recv_chunk(Pid) -> ok | {ok, Bin} | {error, Reason}
Types
Receives a chunk of the remote file (RemoteFile
of recv_chunk_start
). The return values have the following meaning:
-
ok
= the transfer is complete. -
{ok, Bin}
= just another chunk of the file. -
{error, Reason}
= transfer failed.
rename(Pid, Old, New) -> ok | {error, Reason}
Types
Renames Old
to New
at the remote server.
rmdir(Pid, Dir) -> ok | {error, Reason}
Types
Removes directory Dir
at the remote server.
send(Pid, LocalFile) ->
send(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}
Types
Transfers the file LocalFile
to the remote server. If RemoteFile
is specified, the name of the remote file is set to RemoteFile
, otherwise to LocalFile
.
send_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}
Types
Transfers the binary Bin
into the file RemoteFile
at the remote server.
send_chunk(Pid, Bin) -> ok | {error, Reason}
Types
Transfers the chunk Bin
to the remote server, which writes it into the file specified in the call to send_chunk_start/2
.
For some errors, for example, file system full, it is necessary to to call send_chunk_end
to get the proper reason.
send_chunk_start(Pid, File) -> ok | {error, Reason}
Types
Starts transfer of chunks into the file File
at the remote server.
send_chunk_end(Pid) -> ok | {error, Reason}
Types
Stops transfer of chunks to the remote server. The file at the remote server, specified in the call to send_chunk_start/2
is closed by the server.
start_service(ServiceConfig) -> {ok, Pid} | {error, Reason}
Types
Dynamically starts an FTP
session after the ftp
application has been started.
Note
As long as the ftp
application is operational, the FTP sessions are supervised and can be soft code upgraded.
stop_service(Reference) -> ok | {error, Reason}
Types
Stops a started FTP session.
type(Pid, Type) -> ok | {error, Reason}
Types
Sets the file transfer type to ascii
or binary
. When an FTP session is opened, the default transfer type of the server is used, most often ascii
, which is default according to RFC 959
.
user(Pid, User, Password) -> ok | {error, Reason}
Types
Performs login of User
with Password
.
user(Pid, User, Password, Account) -> ok | {error, Reason}
Types
Performs login of User
with Password
to the account specified by Account
.
quote(Pid, Command) -> [FTPLine]
Types
Note
The telnet end of line characters, from the FTP protocol definition, CRLF, for example, "\\r\\n" has been removed.
Sends an arbitrary FTP command and returns verbatim a list of the lines sent back by the FTP server. This function is intended to give application accesses to FTP commands that are server-specific or that cannot be provided by this FTP client.
Note
FTP commands requiring a data connection cannot be successfully issued with this function.