内容

名称

Net::FTP - FTP 客户端类

概要

use Net::FTP;

$ftp = Net::FTP->new("some.host.name", Debug => 0)
  or die "Cannot connect to some.host.name: $@";

$ftp->login("anonymous",'-anonymous@')
  or die "Cannot login ", $ftp->message;

$ftp->cwd("/pub")
  or die "Cannot change working directory ", $ftp->message;

$ftp->get("that.file")
  or die "get failed ", $ftp->message;

$ftp->quit;

描述

Net::FTP 是一个用 Perl 实现的简单 FTP 客户端类，如 RFC959 中所述。它为 RFC959 中常用的命令子集提供包装器。如果安装了 IO::Socket::IP 或 IO::Socket::INET6，它还支持 RFC2428 中定义的 IPv6。如果安装了 IO::Socket::SSL，它还支持 RFC4217 中定义的隐式 FTPS 和显式 FTPS。

Net::FTP 类是 Net::Cmd 的子类，并且（取决于可用性）是 IO::Socket::IP、IO::Socket::INET6 或 IO::Socket::INET 的子类。

概述

FTP 代表文件传输协议。它是一种在网络机器之间传输文件的方式。该协议定义了一个客户端（其命令由本模块提供）和一个服务器（在本模块中未实现）。通信始终由客户端发起，服务器以消息和状态码（有时还包含数据）进行响应。

FTP 协议允许将文件发送到服务器或从服务器获取文件。每次传输都涉及一个 **本地文件**（在客户端上）和一个 **远程文件**（在服务器上）。在本模块中，如果只指定一个文件名，则本地和远程将使用相同的文件名。这意味着传输远程文件 /path/to/file 将尝试将该文件放入本地 /path/to/file 中，除非您指定本地文件名。

该协议还定义了几种标准的 **转换**，文件可以在传输过程中进行这些转换。它们是 ASCII、EBCDIC、二进制和字节。ASCII 是默认类型，表示文件发送者将把行尾转换为标准表示形式，接收者将把这些表示形式转换回其本地表示形式。EBCDIC 表示正在传输的文件采用 EBCDIC 格式。二进制（也称为图像）格式将数据作为连续的比特流发送。字节格式将数据作为字节传输，这些字节的值无论两台机器之间的字节大小差异如何都保持不变（理论上 - 在实践中，您应该只在真正了解自己在做什么的情况下使用这种格式）。此类不支持 EBCDIC 或字节格式，如果尝试使用这些格式，将默认使用二进制格式。

类方法

new([$host][, %options])

这是用于创建新的 Net::FTP 对象的构造函数。$host 是需要建立 FTP 连接的远程主机的名称。

$host 是可选的。如果未提供 $host，则可以将其作为下面描述的 Host 选项传递。

%options 以哈希方式传递，使用键值对。可能的选项包括

Host - 要连接到的 FTP 主机。它可以是单个标量，如 IO::Socket::INET 中为 PeerAddr 选项定义的那样，也可以是对包含要依次尝试的主机的数组的引用。"host" 方法将返回用于连接到主机的值。

Firewall - 充当 FTP 防火墙的机器的名称。这可以通过环境变量 FTP_FIREWALL 覆盖。如果指定了此选项，并且无法直接连接到给定的主机，则连接将建立到防火墙机器，并将字符串 @hostname 附加到登录标识符。这种设置也称为 ftp 代理。

FirewallType - 指示由 Firewall 指定的机器上运行的防火墙类型。这可以通过环境变量 FTP_FIREWALL_TYPE 覆盖。有关允许类型的列表，请参阅 Net::Config 中对 ftp_firewall_type 的描述。

BlockSize - 这是 Net::FTP 在进行传输时使用的块大小。（默认值为 10240）

Port - 用于 FTP 连接的远程机器上的端口号

SSL - 如果连接应从一开始就使用 SSL，而不是稍后使用 starttls 升级。

SSL_* - 将在将控制或数据连接升级到 SSL 时应用的 SSL 参数。您可以使用 IO::Socket::SSL 中记录的 SSL 参数，但它通常会使用正确的参数。

Timeout - 设置超时值（以秒为单位）（默认值为 120）

Debug - 调试级别（请参阅 Net::Cmd 中的调试方法）

Passive - 如果设置为非零值，则所有数据传输将使用被动模式。如果设置为零，则数据传输将使用主动模式。如果机器直接连接到互联网，则被动模式和主动模式应该都能正常工作。在大多数防火墙和 NAT 配置中，被动模式更有可能正常工作。但是，在一些罕见的防火墙配置中，主动模式实际上在被动模式无法工作时有效。一些非常旧的 FTP 服务器可能没有实现被动传输。如果未指定，则传输模式由环境变量 FTP_PASSIVE 设置，或者如果该变量未设置，则由 libnetcfg 实用程序设置。如果以上都不适用，则使用被动模式。

Hash - 如果给定对文件句柄的引用（例如，\*STDERR），则在该文件句柄上每 1024 字节打印一个井号 (#)。这只是为您调用 hash() 方法，以便为所有传输显示井号。当然，您也可以在需要时显式调用 hash()。

LocalAddr - 用于所有套接字连接的本地地址。此参数将传递给超类，即 IO::Socket::INET 或 IO::Socket::IP。

Domain - 要使用的域，即 AF_INET 或 AF_INET6。此参数将传递给 IO::Socket 超类。这可以用于强制使用 IPv4，即使使用 IO::Socket::IP 也会默认使用 IPv6。Family 被接受为 Domain 的替代名称。

如果构造函数失败，将返回 undef，并且错误消息将位于 $@ 中。

对象方法

除非另有说明，否则所有方法都返回 true 或 false 值，其中 true 表示操作成功。当方法声明它返回一个值时，失败将返回为 undef 或一个空列表。

Net::FTP 继承自 Net::Cmd，因此除了此处记录的方法外，还可以使用 Net::Cmd 中定义的方法向远程 FTP 服务器发送命令。

login([$login[, $password[, $account]]])

使用给定的登录信息登录到远程 FTP 服务器。如果没有给出参数，则 Net::FTP 使用 Net::Netrc 包查找连接主机上的登录信息。如果找不到信息，则使用 anonymous 登录。如果没有给出密码并且登录为 anonymous，则将使用 anonymous@ 作为密码。

如果连接通过防火墙，则将调用 authorize 方法，不带参数。

starttls()

将现有纯连接升级到 SSL。SSL 参数必须在 new 中给出，因为它们也需要用于数据连接。

stoptls()

将现有 SSL 连接降级回纯连接。这对于与防火墙中的某些 FTP 助手一起使用是必需的，这些助手需要查看 PORT 和 PASV 命令以及响应以动态打开必要的端口。在这种情况下，starttls 通常只用于保护授权。

prot($level)

设置客户端和服务器将使用的哪种数据通道保护类型。仅支持 $level "C"（清除）和 "P"（私有）。

host()

返回构造函数使用的值，并传递给 IO::Socket 超类以连接到主机。

account($acct)

设置一个字符串来标识用户的帐户。

authorize([$auth[, $resp]])

这是一种由某些防火墙 FTP 代理使用的协议。它用于授权用户发送数据。如果两个参数都没有指定，则 authorize 使用 Net::Netrc 进行查找。

site($args)

向远程服务器发送 SITE 命令并等待响应。

返回响应代码的最高有效位。

ascii()

以 ASCII 格式传输文件。如果需要，将进行 CRLF 转换。

binary()

以二进制模式传输文件。不会进行任何转换。

提示：如果服务器和客户端机器都使用相同的文本文件行结束符，则以二进制模式传输所有文件将更快。

type([$type])

设置或获取文件是否以 ASCII 或二进制模式传输。

rename($oldname, $newname)

将远程 FTP 服务器上的文件从 $oldname 重命名为 $newname。这是通过发送 RNFR 和 RNTO 命令来完成的。

delete($filename)

向服务器发送请求以删除 $filename。

cwd([$dir])

尝试更改目录到 $dir 中给定的目录。如果 $dir 是 ".."，则使用 FTP CDUP 命令尝试向上移动一个目录。如果没有给出目录，则尝试将目录更改为根目录。

cdup()

将目录更改为当前目录的父目录。

passive([$passive])

设置或获取数据连接是否将以被动模式启动。

pwd()

返回当前目录的完整路径名。

restart($where)

设置下一个数据传输开始的字节偏移量。Net::FTP 只是记录此值，并在下次数据传输时使用它。因此，此方法不会返回错误，但设置它可能会导致后续数据传输失败。

rmdir($dir[, $recurse])

删除名为 $dir 的目录。如果 $recurse 为 true，则 rmdir 将尝试删除目录中的所有内容。

mkdir($dir[, $recurse])

创建一个名为 $dir 的新目录。如果 $recurse 为 true，则 mkdir 将尝试创建给定路径中的所有目录。

返回新目录的完整路径名。

alloc($size[, $record_size])

alloc 命令允许您使用 ALLO ftp 命令向 ftp 服务器提供有关即将传输的文件大小的提示。一些存储系统使用此信息来智能地决定如何存储文件。$size 参数表示文件的大小（以字节为单位）。$record_size 参数表示使用记录或页面结构发送的文件的最大记录或页面大小。

对于普通文件，将自动确定文件大小并将其发送到服务器，因此，只有在您从套接字、命名管道或与普通文件无关的其他流传输数据时，才需要调用此方法。

ls([$dir])

获取 $dir 或当前目录的目录列表。

在数组上下文中，返回从服务器返回的行的列表。在标量上下文中，返回对列表的引用。

dir([$dir])

以长格式获取 $dir 或当前目录的目录列表。

在数组上下文中，返回从服务器返回的行的列表。在标量上下文中，返回对列表的引用。

get($remote_file[, $local_file[, $where]])

从服务器获取 $remote_file 并存储在本地。$local_file 可以是文件名或文件句柄。如果未指定，则该文件将存储在当前目录中，其叶节点名称与远程文件相同。

如果给出了 $where，则不会传输文件的第一个 $where 字节，并且如果本地文件已存在，则剩余的字节将追加到本地文件。

返回 $local_file，如果未提供 $local_file，则返回生成的本地文件名。如果遇到错误，则返回 undef。

put($local_file[, $remote_file])

将文件上传到远程服务器。$local_file 可以是文件名或文件句柄。如果 $local_file 是文件句柄，则必须指定 $remote_file。如果未指定 $remote_file，则文件将存储在当前目录中，并使用与 $local_file 相同的叶节点名。

返回 $remote_file，如果未提供 $remote_file，则返回生成的远程文件名。

注意：如果由于某种原因传输未完成并返回错误，则已传输的内容不会自动删除。

put_unique($local_file[, $remote_file])

与 put 相同，但使用 STOU 命令。

返回服务器上文件的名称。

append($local_file[, $remote_file])

与 put 相同，但将内容追加到远程服务器上的文件。

返回 $remote_file，如果未提供 $remote_file，则返回生成的远程文件名。

unique_name()

返回使用 STOU 命令存储在服务器上的最后一个文件的名称。

mdtm($file)

返回给定文件的修改时间

size($file)

返回存储在远程服务器上的给定文件的大小（以字节为单位）。

注意：报告的大小是存储在远程服务器上的文件的大小。如果随后以 ASCII 模式从服务器传输文件，并且远程服务器和本地机器对“行尾”有不同的理解，则传输后本地机器上的文件大小可能不同。

supported($cmd)

如果远程服务器支持给定命令，则返回 TRUE。

hash([$filehandle_glob_ref[, $bytes_per_hash_mark]])

在不带参数的情况下调用，或者第一个参数为 false 时，将抑制哈希标记。如果第一个参数为 true 但不是对文件句柄 glob 的引用，则使用 \*STDERR。第二个参数是每个哈希标记打印的字节数，默认为 1024。在所有情况下，返回值都是对两个元素数组的引用：文件句柄 glob 引用和每个哈希标记的字节数。

feature($name)

确定服务器是否支持指定的特性。返回值是服务器响应的描述其支持的给定特性的选项的行列表。如果特性不受支持，则返回空列表。

if ($ftp->feature( 'MDTM' )) {
  # Do something
}

if (grep { /\bTLS\b/ } $ftp->feature('AUTH')) {
  # Server supports TLS
}

以下方法返回的结果可能不同，具体取决于它们的调用方式。如果用户显式调用pasv或port方法，则这些方法将返回true或false值。如果用户没有调用这些方法中的任何一个，则结果将是对基于Net::FTP::dataconn对象的引用。

nlst([$dir])

向服务器发送NLST命令，并带有一个可选参数。

list([$dir])

与nlst相同，但使用LIST命令

retr($file)

开始从远程服务器检索名为$file的文件。

stor($file)

告诉服务器您希望存储一个文件。$file是要创建的新文件的名称。

stou($file)

与stor相同，但使用STOU命令。在数据连接关闭后，可以通过unique_name方法获得在服务器上创建的唯一文件的名称。

appe($file)

告诉服务器我们希望将一些数据追加到名为$file的文件末尾。如果此文件不存在，则创建它。

如果出于某种原因，您希望完全控制数据连接，包括生成它并在需要时调用response方法，那么用户可以使用这些方法来做到这一点。

但是，调用这些方法只会影响上面那些可以返回数据连接的方法的使用。它们对get、put、put_unique以及不需要数据连接的方法没有影响。

port([$port])
eprt([$port])

向服务器发送PORT（IPv4）或EPRT（IPv6）命令。如果指定了$port，则将其发送到服务器。如果没有，则创建一个监听套接字并将正确的信息发送到服务器。

pasv()
epsv()

告诉服务器进入被动模式（IPv4 为 pasv，IPv6 为 epsv）。返回表示服务器正在监听的端口的文本，此文本适合使用 port 或 eprt 方法发送到另一个 FTP 服务器。

以下方法可用于在两个远程服务器之间传输文件，前提是这两个服务器可以直接相互连接。

pasv_xfer($src_file, $dest_server[, $dest_file ])

此方法将在两个远程 FTP 服务器之间进行文件传输。如果省略 $dest_file，则将使用 $src_file 的叶节点名称。

pasv_xfer_unique($src_file, $dest_server[, $dest_file ])

类似于 pasv_xfer，但文件使用 STOU 命令存储在远程服务器上。

pasv_wait($non_pasv_server)

此方法可用于等待被动服务器和非被动服务器之间的传输完成。该方法应在被动服务器上调用，并将非被动服务器的 Net::FTP 对象作为参数传递。

abort()

中止当前数据传输。

quit()

向远程 FTP 服务器发送 QUIT 命令并关闭套接字连接。

适用于冒险者的方法

quot($cmd[, $args])

向远程服务器发送 Net::FTP 不直接支持的命令，并等待响应。

返回响应代码的最高有效位。

警告 此调用仅应用于不需要数据连接的命令。错误使用此方法会导致连接挂起。

can_inet6()

返回我们是否可以使用 IPv6。

can_ssl()

返回我们是否可以使用 SSL。

dataconn 类

Net::FTP 中定义的一些方法返回一个对象，该对象将从 Net::FTP::dataconn 类派生。有关更多详细信息，请参阅 Net::FTP::dataconn。

未实现

以下 RFC959 命令尚未实现

SMNT

挂载不同的文件系统结构，而不更改登录或帐户信息。

HELP

向服务器询问它接受的命令的“帮助信息”（这是 RFC 中的描述）。

MODE

指定要传输文件的传输模式（流、块或压缩）。

SYST

请求远程服务器系统标识。

STAT

请求远程服务器状态。

STRU

指定要传输文件的结构。

REIN

重新初始化连接，刷新所有 I/O 和帐户信息。

EXPORTS

无.

已知错误

请参阅 https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet。

报告错误

报告错误/问题时，请尽可能多地提供信息。由于几乎每个设置都不同，我可能很难重现问题。

一个可以产生问题的简单脚本可能会有所帮助。如果此脚本在构造函数中传递了额外的选项 Debug => 1 运行，并将输出与错误报告一起发送，这也会很有用。如果您无法包含一个简单的脚本，那么请包含一个从您的程序运行中产生的调试跟踪，该程序确实产生了问题。

另请参阅

Net::Netrc、Net::Cmd、IO::Socket::SSL；

ftp(1)、ftpd(8)；

https://www.ietf.org/rfc/rfc959.txt、https://www.ietf.org/rfc/rfc2428.txt、https://www.ietf.org/rfc/rfc4217.txt。

致谢

Henry Gabryjelski <[email protected]> - 为递归创建目录的建议。

Nathan Torkington <[email protected]> - 为文档提供了一些输入。

Roderick Schertler <[email protected]> - 为各种输入提供帮助

作者

Graham Barr <[email protected]>。

Steve Hay <[email protected]> 自 1.22_02 版本起开始维护 libnet。

版权

版权所有 (C) 1995-2004 Graham Barr。保留所有权利。

版权所有 (C) 2013-2017, 2020, 2022 Steve Hay。保留所有权利。

许可证

本模块是自由软件；您可以根据与 Perl 本身相同的条款重新分发和/或修改它，即根据 GNU 通用公共许可证或 Artistic 许可证的条款，如 LICENCE 文件中所述。

版本

版本 3.15

日期

2023 年 3 月 20 日

历史

请参阅 Changes 文件。