ftp

FTP

模块

FTP

模块摘要

文件传输协议客户端。

描述

此模块根据文件传输协议（FTP）的子集实现文件传输的客户端，请参阅RFC 959。

从Inets4.4.1开始，FTP 客户端总是尝试使用被动 FTP 模式，如果失败则只采用主动 FTP 模式。该默认行为可以通过启动选项进行更改mode。

FTP 客户端可以通过两种方式启动。一个是使用Inets service framework，另一个是直接启动它作为一个独立的过程使用函数open。

有关 FTP 会话的简单示例，请参阅Inets User's Guide。

除了普通函数用于接收和发送的文件（见recv/2，recv/3，send/2，和send/3），有用于接收远程文件作为二进制文件（见功能recv_bin/2）以及用于发送二进制文件被存储为远程文件（见send_bin/3）。

提供了一组功能用于发送和接收文件的连续部分以存储在远程文件中。对于发送，见send_chunk_start/2，send_chunk/2和send_chunk_end/1。接收，请参阅recv_chunk_start/2和recv_chunk/）。

以下函数的返回值很大程度上取决于远程主机上 FTP 服务器的实现。特别是，结果来自ls并且nlist各不相同。通常，真正的错误不会被报告为错误ls，即使例如文件或目录不存在。nlist通常更严格，但如果请求是存在但空的目录内容的列表，则某些实现具有响应错误的特殊行为。

FTP 客户端服务的启动/停止

通过调用Inets应用程序 API inets:start(ftpc, ServiceConfig)，或者inets:start(ftpc, ServiceConfig, How)，可以在运行时动态地启动和停止 FTP 客户端inets:stop(ftpc, Pid)。有关详情，请参阅inets(3)。

可用的配置选项如下所示：

{主机，主机}

宿主=string() | ip_address()

{港口，港口}

港口=integer() > 0

默认是21。

{模式，模式}

模式=active | passive

默认是passive。

{详细，详细}

冗长的boolean()

确定 FTP 通信是否冗长。

默认是false。

{DEBUG，Debug}

调试=trace | debug | disable

使用 dbg 工具包进行调试。

默认是disable。

{ipfamily，IpFamily}

IpFamily=inet | inet6 | inet6fb4

随着inet6fb4客户端的行为之前，也就是试图使用 IPv6，且仅当不工作，它使用的 IPv4）。

默认值是inet（IPv4）。

{超时，超时}

超时=non_neg_integer()

连接暂停。

默认值是60000（毫秒）。

{超时，DTimeout}

DTimeout = non_neg_integer() | infinity

数据连接超时。客户端等待服务器连接到数据套接字的时间。

默认是infinity。

{进步，进步]

进展=ignore | {CBModule, CBFunction, InitProgress}

CBModule = atom()，CBFunction = atom()

InitProgress = term()

默认是ignore。

期权progress用于希望创建某种类型的进度报告的应用程序，例如 GUI 中的进度条。进度选项的默认值为ignore，即不使用该选项。当指定进度选项时，以下情况发生ftp:send/[3,4]或ftp:recv/[3,4]称为：

• 在传输文件之前，进行以下调用以指示文件传输的开始和文件的大小。回调函数的返回值是UserProgressTerm它将在下次调用回调函数时用作输入。CBModule:CBFunction(InitProgress, File, {file_size, FileSize})

• 每次传输一块字节时，都会执行以下调用：

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

• 在文件末尾，进行以下调用以指示传输的结束： CBModule:CBFunction(UserProgressTerm, File, {transfer_size, 0})回调函数的定义如下：CBModule:CBFunction(UserProgressTerm, File, Size) -> UserProgressTermCBModule = CBFunction = atom()UserProgressTerm = term()File = string()Size = {transfer_size, integer()} | {file_size, integer()} | {file_size, unknown}对于远程文件，ftp无法以独立于平台的方式确定文件大小。在这种情况下，大小变成unknown了，并由应用程序决定大小。注意回调由中间人进程完成，因此文件传输不受进程回调函数中代码的影响。如果回调崩溃，FTP 连接过程会检测到这一情况，然后打印信息报告并继续进行，就好像进度选项已设置为ignore。当会话为时，文件传输类型设置为 FTP 服务器的默认设置打开。这通常是 ASCCI 模式。当前的本地工作目录（比较lpwd/1）被设置为file:get_cwd/1所需的本地目录所报告的值。返回值Pid用作所有其他函数中新创建的 FTP 客户端的引用，并且它们将由创建连接的进程调用。FTP 客户端进程监视创建它的进程并在该进程终止时终止。数据类型 FTP 客户端 API 中的多个函数使用以下类型定义：pid()= FTP 连接的标识符string()= ASCII 字符列表shortage_reason()= etnospc | epnospcrestriction_reason()= epath | efnamena | elogin | enotbinary- 全部限制并不总是与所有功能相关common_reason()= econn | eclosed | term()- account(Pid, Account) -> ok | {error, Reason}出错的一些解释出口类型如果需要，为操作提供帐户。append(Pid, LocalFile) ->append(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}TypesTransfers 文件LocalFile到远程服务器。如果RemoteFile指定，则将文件附加到的远程文件的名称设置为RemoteFile，否则设置为LocalFile。如果该文件不存在，则会创建该文件。append_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}类型将二进制文件Bin传输到远程服务器并将其附加到文件RemoteFile。如果该文件不存在，则会创建该文件。append_chunk(Pid, Bin) -> ok | {error, Reason}类型将块Bin传输到远程服务器，将其附加到调用中指定的文件中append_chunk_start/2。对于某些错误（例如文件系统已满），必须调用append_chunk_end以获取正确的原因。append_chunk_start(Pid, File) -> ok | {error, Reason}类型启动传送块以附加到File远程服务器上的文件。如果该文件不存在，则会创建该文件。append_chunk_end(Pid) -> ok | {error, Reason}TypesStops 传输块以附加到远程服务器。远程服务器上的文件（在调用中指定）append_chunk_start/2由服务器关闭。cd(Pid, Dir) -> ok | {error, Reason}Types 将远程服务器上的工作目录更改为Dir。close(Pid) -> okTypes 结束使用函数创建的FTP会话open。delete(Pid, File) -> ok | {error, Reason}类型File在远程服务器上删除文件。formaterror(Tag) -> string()类型给出错误返回值{error, AtomReason}，该函数返回描述错误的可读字符串。lcd(Pid, Dir) -> ok | {error, Reason}TypesChanges 工作目录Dir为本地客户端。lpwd(Pid) -> {ok, Dir}类型返回本地客户端的当前工作目录。ls(Pid) ->ls(Pid, Pathname) -> {ok, Listing} | {error, Reason}类型以长格式返回文件列表。Pathname可以是一个目录，一组文件或一个文件。该Pathname字符串可以包含通配符。ls/1意味着用户当前的远程目录。格式Listing取决于操作系统。在 UNIX 上，它通常是由ls -lshell命令的输出生成的。mkdir(Pid, Dir) -> ok | {error, Reason}Types Dir在远程服务器上创建目录。nlist(Pid) ->nlist(Pid, Pathname) -> {ok, Listing} | {error, Reason}类型以短格式返回文件列表。Pathname可以是一个目录，一组文件或一个文件。该Pathname字符串可以包含通配符。nlist/1意味着用户的当前远程目录。格式Listing是一个文件名流，其中每个文件名由<CRLF>或<NL>分隔。与功能相反ls，其目的nlist是使程序自动处理文件名信息。open(Host) -> {ok, Pid} | {error, Reason}open(Host, Opts) -> {ok, Pid} | {error, Reason}类型启动一个独立的 FTP 客户端进程（没有Inets服务框架）并打开与 FTP 服务器的会话Host。如果选项{tls, tls_options()}存在，FTP 会话将通过tls（ftps，请参阅RFC 4217）传输。该列表tls_options()可以是空的。该功能ssl:connect/3用于保护控制连接和数据会话。以这种方式打开的会话使用函数关闭close。pwd(Pid) -> {ok, Dir} | {error, Reason}类型返回远程服务器上的当前工作目录。recv(Pid, RemoteFile) ->recv(Pid, RemoteFile, LocalFile) -> ok | {error, Reason}类型将文件RemoteFile从远程服务器传输到本地客户端的文件系统。如果LocalFile指定，则本地文件将为LocalFile，否则为RemoteFile。如果文件写入失败（例如，enospc），则该命令被中止并{error, file_write_error_reason()}返回。但是，该文件不是除去。recv_bin(Pid, RemoteFile) -> {ok, Bin} | {error, Reason}类型RemoteFile从远程服务器传输文件并将其作为二进制文件接收。recv_chunk_start(Pid, RemoteFile) -> ok | {error, Reason}Types RemoteFile从远程服务器开始传输文件。recv_chunk(Pid) -> ok | {ok, Bin} | {error, Reason}类型接收远程文件（RemoteFileof recv_chunk_start）的一部分。返回值具有以下含义：

• ok=转让完成。

• {ok, Bin}=只是文件的另一块。

• {error, Reason}=转移失败。

rename(Pid, Old, New) -> ok | {error, Reason}

类型

改名Old到New在远程服务器上。

rmdir(Pid, Dir) -> ok | {error, Reason}

类型

移除目录Dir在远程服务器上。

send(Pid, LocalFile) ->send(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}

类型

将文件传输LocalFile到远程服务器。如果RemoteFile指定，则将远程文件的名称设置为RemoteFile，否则设为LocalFile。

send_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}

类型

传输二进制文件Bin进入档案RemoteFile在远程服务器上。

send_chunk(Pid, Bin) -> ok | {error, Reason}

类型

将块传输Bin到远程服务器，远程服务器将其写入到调用中指定的文件中send_chunk_start/2。

对于一些错误，例如文件系统已满，必须调用send_chunk_end才能得到正确的理由。

send_chunk_start(Pid, File) -> ok | {error, Reason}

类型

开始将块转移到文件中。File在远程服务器上。

send_chunk_end(Pid) -> ok | {error, Reason}

类型

停止将块传输到远程服务器。远程服务器上的文件，在调用send_chunk_start/2被服务器关闭。

type(Pid, Type) -> ok | {error, Reason}

类型

将文件传输类型设置为ascii或binary。打开 FTP 会话时，通常会使用服务器的默认传输类型ascii，这是根据默认设置的默认传输类型RFC 959。

user(Pid, User, Password) -> ok | {error, Reason}

类型

执行的登录User使用Password。

user(Pid, User, Password, Account) -> ok | {error, Reason}

类型

User使用Password指定的帐户执行登录Account。

quote(Pid, Command) -> [FTPLine]

类型

注意

来自 FTP 协议定义 CRLF（例如“\ r \ n”）的行字符的 telnet 结尾已被删除。

发送一个任意的 FTP 命令并逐字返回由 FTP 服务器发回的行的列表。此功能旨在为应用程序访问特定于服务器或不能由此FTP客户端提供的 FTP 命令。

注意

使用此功能无法成功发出需要数据连接的 FTP 命令。

错误

返回的可能错误原因和相应的诊断字符串。formaterror/1如下：

echunk

根据下列之一发送块时出现同步错误：

• 调用send_chunk/2或send_chunk_end/1调用前send_chunk_start/2。

• 在块发送期间，即在调用之前，已经对另一个传送功能进行了呼叫send_chunk_end/1。

eclosed

会议结束。

econn

连接到远程服务器过早关闭。

ehost

未找到主机，找不到 FTP 服务器，或连接被 FTP 服务器拒绝。

elogin

用户未登录。

enotbinary

术语不是二元的。

epath

没有这样的文件或目录，或目录已经存在，或权限被拒绝。

etype

没有这种类型。

euser

无效的用户名或密码。

etnospc

系统452中的存储空间不足。

epnospc

超出存储分配（针对当前目录或数据集）552。

efnamena

文件名不允许553。

另见

file(3) filename(3)和J. Postel和J. Reynolds：File Transfer Protocol（RFC 959）。