From e0ee349fc426007c7b269660244aeda94ddadd9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= Date: Mon, 26 Feb 2018 16:35:58 +0100 Subject: inets,ftp: Break out FTP from inets - Created initial directory structure for the FTP application. - Updated inets Makefiles to not include FTP related modules. - Remove ftp code from inets - Implement backward compatibility layer for FTP - Add inets_ftp_wrapper - Fix failing TCs Change-Id: I120ec5bdef0c3df4cee2d7880db2aec581505bc4 --- lib/ftp/doc/src/ftp.xml | 948 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 948 insertions(+) create mode 100644 lib/ftp/doc/src/ftp.xml (limited to 'lib/ftp/doc/src/ftp.xml') diff --git a/lib/ftp/doc/src/ftp.xml b/lib/ftp/doc/src/ftp.xml new file mode 100644 index 0000000000..42bece4d38 --- /dev/null +++ b/lib/ftp/doc/src/ftp.xml @@ -0,0 +1,948 @@ + + + + +
+ + 19972016 + Ericsson AB. All Rights Reserved. + + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + + + ftp + Peter Högfeldt + + 1997-11-05 + B + ftp.xml +
+ ftp + 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.

+ +

As from Inets 4.4.1, 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.

+ + + +

An FTP client can be started in two ways. One is using the + Inets service framework, + the other is to start it directly as a standalone process + using function open.

+ +

For a simple example of an FTP session, see + Inets User's Guide.

+ +

In addition to the ordinary functions for receiving and sending + files (see recv/2, recv/3, send/2, and + send/3) there are functions for receiving remote files as + binaries (see recv_bin/2) and for sending binaries to be + stored as remote files (see send_bin/3).

+ +

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.

+ + + + +
+ FTP CLIENT SERVICE START/STOP + +

The FTP client can be started and stopped dynamically in runtime by + calling the Inets application API + inets:start(ftpc, ServiceConfig), + or inets:start(ftpc, ServiceConfig, How), and + inets:stop(ftpc, Pid). + For details, see inets(3).

+ +

The available configuration options are as follows:

+ + + {host, Host} + + +

Host = string() | ip_address()

+ + + {port, Port} + + +

Port = integer() > 0

+

Default is 21.

+ + + {mode, Mode} + + +

Mode = active | passive

+

Default is passive.

+ + + {verbose, Verbose} + + +

Verbose = boolean()

+

Determines if the FTP communication is to be + verbose or not.

+

Default is false.

+ + + {debug, Debug} + + +

Debug = trace | debug | disable

+

Debugging using the dbg toolkit.

+

Default is disable.

+ + + {ipfamily, IpFamily} + + +

IpFamily = inet | inet6 | inet6fb4

+

With inet6fb4 the client behaves as before, that is, + tries to use IPv6, and only if that does not work it + uses IPv4).

+

Default is inet (IPv4).

+ + + {timeout, Timeout} + + +

Timeout = non_neg_integer()

+

Connection time-out.

+

Default is 60000 (milliseconds).

+ + + {dtimeout, DTimeout} + + +

DTimeout = non_neg_integer() | infinity

+

Data connect time-out. + The time the client waits for the server to connect to the + data socket.

+

Default is infinity.

+ + + {progress, Progress} + + +

Progress = ignore | {CBModule, CBFunction, InitProgress}

+

CBModule = atom(), CBFunction = atom()

+

InitProgress = term()

+

Default is ignore.

+ + + + +

Option progress is intended to be used by applications that + want to create some type of progress report, such as a progress bar in + a GUI. Default for the progress option is ignore, + that is, the option is not used. When the progress option is + specified, the following happens when ftp:send/[3,4] or + ftp:recv/[3,4] are called:

+ + + +

Before a file is transferred, the following call is + made to indicate the start of the file transfer and how large + the file is. The return value of the callback function + is to be a new value for the UserProgressTerm that will + be used as input the next time the callback function is + called.

+

+ CBModule:CBFunction(InitProgress, File, {file_size, FileSize}) +

+ + + +

Every time a chunk of bytes is transferred the + following call is made:

+

+ CBModule:CBFunction(UserProgressTerm, File, {transfer_size, TransferSize}) +

+ + + +

At the end of the file the following call is + made to indicate the end of the transfer:

+

+ CBModule:CBFunction(UserProgressTerm, File, {transfer_size, 0}) +

+ + + +

The callback function is to be defined as follows:

+ +

+ CBModule:CBFunction(UserProgressTerm, File, Size) -> UserProgressTerm +

+ +

+ CBModule = CBFunction = atom() +

+ +

+ UserProgressTerm = term() +

+ +

+ File = string() +

+ +

+ Size = {transfer_size, integer()} | {file_size, integer()} | {file_size, unknown} +

+ +

For remote files, ftp cannot determine the + file size in a platform independent way. In this case the size + becomes unknown and it is left to the application to + determine the size.

+ + +

The callback is made by a middleman process, hence the + file transfer is not affected by the code in the progress + callback function. If the callback crashes, this is + detected by the FTP connection process, which then prints an + info-report and goes on as if the progress option was set + to ignore.

+ + +

The file transfer type is set to the default of the FTP server + when the session is opened. This is usually ASCCI mode. +

+ +

The current local working directory (compare lpwd/1) is set + to the value reported by file:get_cwd/1, the wanted + local directory. +

+ +

The return value Pid is used as a reference to the + newly created FTP client in all other functions, and they are to + be called by the process that created the connection. The FTP + client process monitors the process that created it and + terminates if that process terminates.

+
+ +
+ DATA TYPES +

The following type definitions are used by more than one + function in the FTP client API:

+

pid() = identifier of an FTP connection

+

string() = list of ASCII characters

+

shortage_reason() = etnospc | epnospc

+

restriction_reason() = epath | efnamena | elogin | enotbinary + - all restrictions are not always relevant to all functions +

+

common_reason() = econn | eclosed | term() + - some explanation of what went wrong

+ + +
+ + + + account(Pid, Account) -> ok | {error, Reason} + Specifies which account to use. + + Pid = pid() + Account = string() + Reason = eacct | common_reason() + + +

Sets the account for an operation, if needed.

+ + + + + + + + + append(Pid, LocalFile) -> + append(Pid, LocalFile, RemoteFile) -> ok | {error, Reason} + Transfers a file to remote server, and appends it to + Remotefile. + + Pid = pid() + LocalFile = RemoteFile = string() + Reason = epath | elogin | etnospc | epnospc | efnamena | common_reason + + +

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} + Transfers a binary into a remote file. + + Pid = pid() + Bin = binary()() + RemoteFile = string() + Reason = restriction_reason()| shortage_reason() | common_reason() + + +

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} + Appends a chunk to the remote file. + + Pid = pid() + Bin = binary() + Reason = echunk | restriction_reason() | common_reason() + + +

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} + Starts transfer of file chunks for appending to File. + + Pid = pid() + File = string() + Reason = restriction_reason() | common_reason() + + +

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} + Stops transfer of chunks for appending. + + Pid = pid() + Reason = echunk | restriction_reason() | shortage_reason() + + +

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} + Changes remote working directory. + + Pid = pid() + Dir = string() + Reason = restriction_reason() | common_reason() + + +

Changes the working directory at the remote server to + Dir.

+ + + + + + + close(Pid) -> ok + Ends the FTP session. + + Pid = pid() + + +

Ends an FTP session, created using function + open.

+ + + + + + + delete(Pid, File) -> ok | {error, Reason} + Deletes a file at the remote server. + + Pid = pid() + File = string() + Reason = restriction_reason() | common_reason() + + +

Deletes the file File at the remote server.

+ + + + + + + formaterror(Tag) -> string() + Returns error diagnostics. + + Tag = {error, atom()} | atom() + + +

Given an error return value {error, AtomReason}, + this function returns a readable string describing the error.

+ + + + + + + lcd(Pid, Dir) -> ok | {error, Reason} + Changes local working directory. + + Pid = pid() + Dir = string() + Reason = restriction_reason() + + +

Changes the working directory to Dir for the local client.

+ + + + + + + lpwd(Pid) -> {ok, Dir} + Gets local current working directory. + + Pid = pid() + + +

Returns the current working directory at the local client.

+ + + + + + + + + ls(Pid) -> + ls(Pid, Pathname) -> {ok, Listing} | {error, Reason} + List of files. + + Pid = pid() + Pathname = string() + Listing = string() + Reason = restriction_reason() | common_reason() + + +

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} + Creates a remote directory. + + Pid = pid() + Dir = string() + Reason = restriction_reason() | common_reason() + + +

Creates the directory Dir at the remote server.

+ + + + + + + + + nlist(Pid) -> + nlist(Pid, Pathname) -> {ok, Listing} | {error, Reason} + List of files. + + Pid = pid() + Pathname = string() + Listing = string() + Reason = restriction_reason() | common_reason() + + +

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} + Starts a standalone FTP client. + + Host = string() | ip_address() + Opts = options() + options() = [option()] + option() = start_option() | open_option() + start_option() = {verbose, verbose()} | {debug, debug()} + verbose() = boolean() (default is false) + debug() = disable | debug | trace (default is disable) + open_option() = {ipfamily, ipfamily()} | {port, port()} | {mode, mode()} | {tls, tls_options()} | {timeout, timeout()} | {dtimeout, dtimeout()} | {progress, progress()} + ipfamily() = inet | inet6 | inet6fb4 (default is inet) + port() = integer() > 0 (default is 21) + mode() = active | passive (default is passive) + tls_options() = [ssl:ssloption()] + timeout() = integer() > 0 (default is 60000 milliseconds) + dtimeout() = integer() > 0 | infinity (default is infinity) + pogress() = ignore | {module(), function(), initial_data()} (default is ignore) + module() = atom() + function() = atom() + initial_data() = term() + Reason = ehost | term() + + + +

Starts a standalone FTP client process + (without the Inets 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} + Gets the remote current working directory. + + Pid = pid() + Reason = restriction_reason() | common_reason() + + +

Returns the current working directory at the remote server.

+ + + + + + + + + recv(Pid, RemoteFile) -> + recv(Pid, RemoteFile, LocalFile) -> ok | {error, Reason} + Transfers a file from remote server. + + Pid = pid() + RemoteFile = LocalFile = string() + Reason = restriction_reason() | common_reason() | file_write_error_reason() + file_write_error_reason() = see file:write/2 + + +

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} + Transfers a file from remote server as a binary. + + Pid = pid() + Bin = binary() + RemoteFile = string() + Reason = restriction_reason() | common_reason() + + +

Transfers the file RemoteFile from the remote server and + receives it as a binary.

+ + + + + + + recv_chunk_start(Pid, RemoteFile) -> ok | {error, Reason} + Starts chunk-reading of the remote file. + + Pid = pid() + RemoteFile = string() + Reason = restriction_reason() | common_reason() + + +

Starts transfer of the file RemoteFile from the + remote server.

+ + + + + + + recv_chunk(Pid) -> ok | {ok, Bin} | {error, Reason} + Receives a chunk of the remote file. + + Pid = pid() + Bin = binary() + Reason = restriction_reason() | common_reason() + + +

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} + Renames a file at the remote server. + + Pid = pid() + CurrFile = NewFile = string() + Reason = restriction_reason() | common_reason() + + +

Renames Old to New at the remote server.

+ + + + + + + rmdir(Pid, Dir) -> ok | {error, Reason} + Removes a remote directory. + + Pid = pid() + Dir = string() + Reason = restriction_reason() | common_reason() + + +

Removes directory Dir at the remote server.

+ + + + + + + + + send(Pid, LocalFile) -> + send(Pid, LocalFile, RemoteFile) -> ok | {error, Reason} + Transfers a file to the remote server. + + Pid = pid() + LocalFile = RemoteFile = string() + Reason = restriction_reason() | common_reason() | shortage_reason() + + +

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} + Transfers a binary into a remote file. + + Pid = pid() + Bin = binary()() + RemoteFile = string() + Reason = restriction_reason() | common_reason() | shortage_reason() + + +

Transfers the binary Bin into the file RemoteFile + at the remote server.

+ + + + + + + send_chunk(Pid, Bin) -> ok | {error, Reason} + Writes a chunk to the remote file. + + Pid = pid() + Bin = binary() + Reason = echunk | restriction_reason() | common_reason() + + +

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} + Starts transfer of file chunks. + + Pid = pid() + File = string() + Reason = restriction_reason() | common_reason() + + +

Starts transfer of chunks into the file File at the + remote server.

+ + + + + + + send_chunk_end(Pid) -> ok | {error, Reason} + Stops transfer of chunks. + + Pid = pid() + Reason = restriction_reason() | common_reason() | shortage_reason() + + +

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.

+ + + + + + + type(Pid, Type) -> ok | {error, Reason} + Sets transfer type to asciior binary. + + Pid = pid() + Type = ascii | binary + Reason = etype | restriction_reason() | common_reason() + + +

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} + User login. + + Pid = pid() + User = Password = string() + Reason = euser | common_reason() + + +

Performs login of User with Password.

+ + + + + + + user(Pid, User, Password, Account) -> ok | {error, Reason} + User login. + + Pid = pid() + User = Password = string() + Reason = euser | common_reason() + + +

Performs login of User with Password to the account + specified by Account.

+ + + + + + + quote(Pid, Command) -> [FTPLine] + Sends an arbitrary FTP command. + + Pid = pid() + Command = string() + FTPLine = string( + +

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.

+ +

FTP commands requiring a data connection cannot be + successfully issued with this function.

+ + + + + +
+ ERRORS +

The possible error reasons and the corresponding diagnostic strings + returned by formaterror/1 are as follows: +

+ + echunk + +

Synchronization error during chunk sending according to one + of the following: +

+ A call is made to send_chunk/2 or send_chunk_end/1 + before a call to send_chunk_start/2. + A call has been made to another transfer function during chunk + sending, that is, before a call to send_chunk_end/1. + + + eclosed + +

The session is closed.

+ + econn + +

Connection to the remote server is prematurely closed.

+ + ehost + +

Host is not found, FTP server is not found, or connection is rejected + by FTP server.

+ + elogin + +

User is not logged in.

+ + enotbinary + +

Term is not a binary.

+ + epath + +

No such file or directory, or directory already exists, or + permission denied.

+ + etype + +

No such type.

+ + euser + +

Invalid username or password.

+ + etnospc + +

Insufficient storage space in system [452].

+ + epnospc + +

Exceeded storage allocation (for current directory or + dataset) [552].

+ + efnamena + +

Filename not allowed [553].

+ + +
+ +
+ SEE ALSO +

file(3) + filename(3) + and J. Postel and J. Reynolds: File Transfer Protocol + (RFC 959). +

+
+ + + + -- cgit v1.2.3