尧图网页设计 
curl/libcurl 的 CURLOPT_ACCEPTTIMEOUT_MS掌控 FTP 主动模式下服务器回连等待超时【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl导读CURLOPT_ACCEPTTIMEOUT_MS是 libcurl 提供的毫秒级超时选项专门用于FTP 主动Active模式下、客户端等待 FTP 服务器反向建立数据连接的时间上限。本文以 docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md 为核心结合 libcurl 源码lib/ftp.c、lib/setopt.c、lib/cf-socket.c讲解该选项的语义、默认值、生效条件与底层实现并给出可运行的 C 代码与命令行对照用法。读完本文你将能准确为基于 libcurl 的 FTP 主动模式传输配置合理的回连超时避免因服务器迟迟不回连而无限期挂起。选项概述它解决什么问题FTP 协议在传输数据时需要建立两条连接一条用于发送命令的控制连接默认 21 端口一条用于传输数据的数据连接。数据连接的建立方式有两种主动模式Active / PORT / EPRT客户端在本机监听一个端口然后通过PORTIPv4或EPRTIPv6命令把该地址告知服务器由服务器反向发起 TCP 连接回到客户端。此时客户端是一个等待方。被动模式Passive / PASV / EPSV客户端向服务器请求一个地址端口由客户端主动去连接服务器。这是 libcurl 的默认行为。CURLOPT_ACCEPTTIMEOUT_MS设置的正是主动模式下客户端等待服务器连接回来的最大毫秒数。原文档明确说明使用主动 FTP 时客户端libcurl让服务器向客户端做一次 TCP 回连而不是被动 FTP 中由客户端去连接服务器。该选项对被动 FTP 没有任何意义。因此该选项只对主动 FTP 生效被动模式下设置它会被忽略。使用方法与参数语义函数签名#include curl/curl.h CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPTTIMEOUT_MS, long ms);参数ms是一个long类型的毫秒值通过curl_easy_setopt传给句柄。它在 libcurl 的选项注册表中登记为CURLOT_LONG类型见 lib/easyoptions.c并被列入公开的字符串名ACCEPTTIMEOUT_MS可用于curl_easy_option_by_name之类的运行时查询。默认值默认值为60000 毫秒60 秒。该常量定义于 lib/ftp.h#define DEFAULT_ACCEPT_TIMEOUT 60000 /* milliseconds one minute */传 0 的含义从 lib/urldata.h 中存储字段的注释可以看到timediff_t accepttimeout; /* in milliseconds, 0 means no timeout */字段注释虽写作0 表示无超时但从实际使用路径看传 0 时的行为需要结合两处源码综合理解在 lib/ftp.c 的主动模式入口中超时值按如下方式选取Curl_expire(data, (data-set.accepttimeout 0) ? >timediff_t timeout_ms DEFAULT_ACCEPT_TIMEOUT; #ifndef CURL_DISABLE_FTP if(data-set.accepttimeout 0) timeout_ms >static CURLcode setopt_set_timeout_ms(timediff_t *ptimeout_ms, long ms) { if(ms 0) return CURLE_BAD_FUNCTION_ARGUMENT; #if LONG_MAX TIMEDIFF_T_MAX if(ms TIMEDIFF_T_MAX) { *ptimeout_ms TIMEDIFF_T_MAX; return CURLE_OK; } #endif *ptimeout_ms (timediff_t)ms; return CURLE_OK; }可见传入负数会返回CURLE_BAD_FUNCTION_ARGUMENT设置失败在long宽度大于timediff_t的平台上超大的正数会被钳制为TIMEDIFF_T_MAX避免溢出正常值则直接以毫秒存入。完整示例代码原文档给出的示例设置 5 秒等待回连如下可直接编译运行#include curl/curl.h int main(void) { CURL *curl curl_easy_init(); if(curl) { CURLcode result; curl_easy_setopt(curl, CURLOPT_URL, ftp://example.com/path/file); /* wait no more than 5 seconds for the FTP server to connect */ curl_easy_setopt(curl, CURLOPT_ACCEPTTIMEOUT_MS, 5000L); result curl_easy_perform(curl); curl_easy_cleanup(curl); } }需要强调的是仅设置该选项并不会自动启用主动模式。主动模式必须配合CURLOPT_FTPPORT一起使用。在 lib/setopt.c 中CURLOPT_FTPPORT的设置逻辑为case CURLOPT_FTPPORT: /* * Use FTP PORT, this also specifies which IP address to use */ result Curl_setstropt(data, STRING_FTPPORT, ptr); s-ftp_use_port !!CURL_EASY_STR(data, STRING_FTPPORT); break;只要CURLOPT_FTPPORT被设置了非空字符串ftp_use_port即为真FTP 状态机随后在 lib/ftp.c 中据此选择PORT/EPRT主动流程而不是默认的PASVelse if(data-set.ftp_use_port) { /* We have chosen to use the PORT (or similar) command */ result ftp_state_use_port(data, ftpc, EPRT); } else { /* We have chosen (this is default) to use the PASV (or similar) command */ ... }仓库自带的示例 docs/examples/ftpuploadresume.c 完整展示了这一组合用法/* enable active mode */ curl_easy_setopt(curl, CURLOPT_FTPPORT, -); /* allow the server no more than 7 seconds to connect back */ curl_easy_setopt(curl, CURLOPT_ACCEPTTIMEOUT_MS, 7000L);其中CURLOPT_FTPPORT传-表示让 libcurl 自动选用本地地址与随机端口进行监听是主动模式最常用的取值。CURLOPT_FTPPORT的完整语法(ipv4|ipv6|domain|interface)?(:port(-range)?)?可参见 lib/ftp.c 中的解析注释及 CURLOPT_FTPPORT 手册。底层实现从监听套接字到超时触发理解该选项的生效过程需要看主动模式在 libcurl 内部的状态机流转建立监听套接字在ftp_state_use_port()lib/ftp.c中libcurl 解析CURLOPT_FTPPORT字符串确定地址与端口范围依次完成 DNS 解析、ftp_port_open_socket()打开套接字、ftp_port_bind_socket()绑定、ftp_port_listen()进入监听随后把监听套接字挂到SECONDARYSOCKET对应的连接过滤器上并通过ftp_port_send_command()向服务器发送PORT/EPRT命令。登记等待超时监听建立成功后立即用当前超时值用户设置值或默认 60000ms注册一个EXPIRE_FTP_ACCEPT定时器Curl_expire(data, (data-set.accepttimeout 0) ? >等待服务器回连在收到服务器响应后的ftp_state_get_resp()分支中lib/ftp.c若处于主动模式ftp_use_port为真libcurl 会尝试Curl_conn_connect(data, SECONDARYSOCKET, FALSE, connected)完成数据连接如果连接尚未就绪则置ftpc-wait_data_conn TRUE进入等待状态直到服务器真正连回或超时定时器到期。超时判定取更短者在 socket 过滤器的cf_tcp_accept_timeleft()中lib/cf-socket.c除了本选项的超时还会与通用的剩余时间Curl_timeleft_ms(data)即CURLOPT_TIMEOUT_MS等全局超时约束做比较并取更短的值作为实际等待上限/* check if the generic timeout possibly is set shorter */ other_ms Curl_timeleft_ms(data); if(other_ms (other_ms timeout_ms)) ...这意味着CURLOPT_ACCEPTTIMEOUT_MS与全局CURLOPT_TIMEOUT_MS是叠加约束关系回连等待不会超过两者中更短的那个。与其他超时选项的区分该选项仅覆盖主动 FTP 下服务器回连数据连接这一个阶段与以下选项职责不同选项作用阶段默认值适用协议CURLOPT_ACCEPTTIMEOUT_MSFTP 主动模式等待服务器回连60000 ms仅 FTP主动模式CURLOPT_CONNECTTIMEOUT_MS建立连接阶段DNS 握手协商300000 ms传 0 时所有协议CURLOPT_TIMEOUT_MS整个操作的总时长上限0无限制所有协议其中CURLOPT_CONNECTTIMEOUT_MS的语义详见 docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md它只限制连接建立阶段一旦连接完成便不再起作用而CURLOPT_TIMEOUT_MS是覆盖全程的总超时。三者在 libcurl 内部共用setopt_set_timeout_ms()做参数校验但作用于完全不同的阶段CURLOPT_ACCEPTTIMEOUT_MS只关心数据连接回连这一瞬。可用性、返回值与编译前提可用性该选项自 libcurl7.24.0起引入见原文档 front-matter 的Added-in字段。协议范围仅适用于FTP含 FTPS 的主动模式场景对其他协议无效。编译前提该选项的注册与存储字段都包裹在#ifndef CURL_DISABLE_FTP条件编译中lib/setopt.c、lib/urldata.h。也就是说使用-DCURL_DISABLE_FTP裁剪掉 FTP 支持的构建中本选项不存在调用会以CURLE_UNKNOWN_OPTION之类的错误失败。返回值curl_easy_setopt()返回CURLcode。CURLE_OK (0)表示设置成功非零表示出错如传入负数得到CURLE_BAD_FUNCTION_ARGUMENT。具体错误码含义参见 docs/libcurl/libcurl-errors.md。命令行对照curl 工具中的对应能力在 curl 命令行工具中主动模式由--ftp-port-P开关启用例如curl --ftp-port - --accept-timeout 5 ftp://example.com/path/file不过需要说明--accept-timeout对应的是命令行工具另一套等待服务器响应的超时语义而命令行工具本身并没有直接暴露CURLOPT_ACCEPTTIMEOUT_MS的独立参数。要在命令行场景精确控制主动模式回连超时通常通过全局--connect-timeout与总时长--max-time间接约束或直接使用 libcurl API 编写程序如上文示例。这是使用该选项时最容易混淆的一点务必区分。实战建议只与CURLOPT_FTPPORT组合使用单独设置本选项不会启用主动模式也不会产生任何效果。考虑 NAT / 防火墙环境主动模式要求服务器能反向连回客户端这在客户端处于 NAT 或防火墙后时常失败。此时应把回连超时调短如 510 秒以便快速失败或改用被动模式libcurl 默认规避。善用默认值多数情况下 60 秒的默认值偏保守若业务对响应时间敏感建议显式设置更小的毫秒值同时留意全局CURLOPT_TIMEOUT_MS会截短本选项的等待上限。检查构建配置如果你的 libcurl 是裁剪版禁用了 FTP该选项不可用代码中应做好错误处理。参考官方示例仓库 docs/examples/ftpuploadresume.c 提供了主动模式 回连超时的完整可运行范例适合作为上手模板。总结CURLOPT_ACCEPTTIMEOUT_MS是 libcurl 为 FTP 主动模式量身定制的等待超时选项它以毫秒为单位、默认 60000ms、负数非法、仅对主动 FTP 生效并与CURLOPT_FTPPORT协同工作。从 lib/ftp.c 的状态机到 lib/cf-socket.c 的过滤器超时计算整条实现链路清晰可查。理解它的生效边界与默认值行为能帮助你在主动 FTP 场景中精确控制等待时长写出更健壮的传输代码。【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 curl/libcurl 的 CURLOPT_ACCEPTTIMEOUT_MS：掌控 FTP 主动模式下服务器回连等待超时
curl/libcurl 的 CURLOPT_ACCEPTTIMEOUT_MS掌控 FTP 主动模式下服务器回连等待超时【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl导读CURLOPT_ACCEPTTIMEOUT_MS是 libcurl 提供的毫秒级超时选项专门用于FTP 主动Active模式下、客户端等待 FTP 服务器反向建立数据连接的时间上限。本文以 docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.md 为核心结合 libcurl 源码lib/ftp.c、lib/setopt.c、lib/cf-socket.c讲解该选项的语义、默认值、生效条件与底层实现并给出可运行的 C 代码与命令行对照用法。读完本文你将能准确为基于 libcurl 的 FTP 主动模式传输配置合理的回连超时避免因服务器迟迟不回连而无限期挂起。选项概述它解决什么问题FTP 协议在传输数据时需要建立两条连接一条用于发送命令的控制连接默认 21 端口一条用于传输数据的数据连接。数据连接的建立方式有两种主动模式Active / PORT / EPRT客户端在本机监听一个端口然后通过PORTIPv4或EPRTIPv6命令把该地址告知服务器由服务器反向发起 TCP 连接回到客户端。此时客户端是一个等待方。被动模式Passive / PASV / EPSV客户端向服务器请求一个地址端口由客户端主动去连接服务器。这是 libcurl 的默认行为。CURLOPT_ACCEPTTIMEOUT_MS设置的正是主动模式下客户端等待服务器连接回来的最大毫秒数。原文档明确说明使用主动 FTP 时客户端libcurl让服务器向客户端做一次 TCP 回连而不是被动 FTP 中由客户端去连接服务器。该选项对被动 FTP 没有任何意义。因此该选项只对主动 FTP 生效被动模式下设置它会被忽略。使用方法与参数语义函数签名#include curl/curl.h CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPTTIMEOUT_MS, long ms);参数ms是一个long类型的毫秒值通过curl_easy_setopt传给句柄。它在 libcurl 的选项注册表中登记为CURLOT_LONG类型见 lib/easyoptions.c并被列入公开的字符串名ACCEPTTIMEOUT_MS可用于curl_easy_option_by_name之类的运行时查询。默认值默认值为60000 毫秒60 秒。该常量定义于 lib/ftp.h#define DEFAULT_ACCEPT_TIMEOUT 60000 /* milliseconds one minute */传 0 的含义从 lib/urldata.h 中存储字段的注释可以看到timediff_t accepttimeout; /* in milliseconds, 0 means no timeout */字段注释虽写作0 表示无超时但从实际使用路径看传 0 时的行为需要结合两处源码综合理解在 lib/ftp.c 的主动模式入口中超时值按如下方式选取Curl_expire(data, (data-set.accepttimeout 0) ? >timediff_t timeout_ms DEFAULT_ACCEPT_TIMEOUT; #ifndef CURL_DISABLE_FTP if(data-set.accepttimeout 0) timeout_ms >static CURLcode setopt_set_timeout_ms(timediff_t *ptimeout_ms, long ms) { if(ms 0) return CURLE_BAD_FUNCTION_ARGUMENT; #if LONG_MAX TIMEDIFF_T_MAX if(ms TIMEDIFF_T_MAX) { *ptimeout_ms TIMEDIFF_T_MAX; return CURLE_OK; } #endif *ptimeout_ms (timediff_t)ms; return CURLE_OK; }可见传入负数会返回CURLE_BAD_FUNCTION_ARGUMENT设置失败在long宽度大于timediff_t的平台上超大的正数会被钳制为TIMEDIFF_T_MAX避免溢出正常值则直接以毫秒存入。完整示例代码原文档给出的示例设置 5 秒等待回连如下可直接编译运行#include curl/curl.h int main(void) { CURL *curl curl_easy_init(); if(curl) { CURLcode result; curl_easy_setopt(curl, CURLOPT_URL, ftp://example.com/path/file); /* wait no more than 5 seconds for the FTP server to connect */ curl_easy_setopt(curl, CURLOPT_ACCEPTTIMEOUT_MS, 5000L); result curl_easy_perform(curl); curl_easy_cleanup(curl); } }需要强调的是仅设置该选项并不会自动启用主动模式。主动模式必须配合CURLOPT_FTPPORT一起使用。在 lib/setopt.c 中CURLOPT_FTPPORT的设置逻辑为case CURLOPT_FTPPORT: /* * Use FTP PORT, this also specifies which IP address to use */ result Curl_setstropt(data, STRING_FTPPORT, ptr); s-ftp_use_port !!CURL_EASY_STR(data, STRING_FTPPORT); break;只要CURLOPT_FTPPORT被设置了非空字符串ftp_use_port即为真FTP 状态机随后在 lib/ftp.c 中据此选择PORT/EPRT主动流程而不是默认的PASVelse if(data-set.ftp_use_port) { /* We have chosen to use the PORT (or similar) command */ result ftp_state_use_port(data, ftpc, EPRT); } else { /* We have chosen (this is default) to use the PASV (or similar) command */ ... }仓库自带的示例 docs/examples/ftpuploadresume.c 完整展示了这一组合用法/* enable active mode */ curl_easy_setopt(curl, CURLOPT_FTPPORT, -); /* allow the server no more than 7 seconds to connect back */ curl_easy_setopt(curl, CURLOPT_ACCEPTTIMEOUT_MS, 7000L);其中CURLOPT_FTPPORT传-表示让 libcurl 自动选用本地地址与随机端口进行监听是主动模式最常用的取值。CURLOPT_FTPPORT的完整语法(ipv4|ipv6|domain|interface)?(:port(-range)?)?可参见 lib/ftp.c 中的解析注释及 CURLOPT_FTPPORT 手册。底层实现从监听套接字到超时触发理解该选项的生效过程需要看主动模式在 libcurl 内部的状态机流转建立监听套接字在ftp_state_use_port()lib/ftp.c中libcurl 解析CURLOPT_FTPPORT字符串确定地址与端口范围依次完成 DNS 解析、ftp_port_open_socket()打开套接字、ftp_port_bind_socket()绑定、ftp_port_listen()进入监听随后把监听套接字挂到SECONDARYSOCKET对应的连接过滤器上并通过ftp_port_send_command()向服务器发送PORT/EPRT命令。登记等待超时监听建立成功后立即用当前超时值用户设置值或默认 60000ms注册一个EXPIRE_FTP_ACCEPT定时器Curl_expire(data, (data-set.accepttimeout 0) ? >等待服务器回连在收到服务器响应后的ftp_state_get_resp()分支中lib/ftp.c若处于主动模式ftp_use_port为真libcurl 会尝试Curl_conn_connect(data, SECONDARYSOCKET, FALSE, connected)完成数据连接如果连接尚未就绪则置ftpc-wait_data_conn TRUE进入等待状态直到服务器真正连回或超时定时器到期。超时判定取更短者在 socket 过滤器的cf_tcp_accept_timeleft()中lib/cf-socket.c除了本选项的超时还会与通用的剩余时间Curl_timeleft_ms(data)即CURLOPT_TIMEOUT_MS等全局超时约束做比较并取更短的值作为实际等待上限/* check if the generic timeout possibly is set shorter */ other_ms Curl_timeleft_ms(data); if(other_ms (other_ms timeout_ms)) ...这意味着CURLOPT_ACCEPTTIMEOUT_MS与全局CURLOPT_TIMEOUT_MS是叠加约束关系回连等待不会超过两者中更短的那个。与其他超时选项的区分该选项仅覆盖主动 FTP 下服务器回连数据连接这一个阶段与以下选项职责不同选项作用阶段默认值适用协议CURLOPT_ACCEPTTIMEOUT_MSFTP 主动模式等待服务器回连60000 ms仅 FTP主动模式CURLOPT_CONNECTTIMEOUT_MS建立连接阶段DNS 握手协商300000 ms传 0 时所有协议CURLOPT_TIMEOUT_MS整个操作的总时长上限0无限制所有协议其中CURLOPT_CONNECTTIMEOUT_MS的语义详见 docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.md它只限制连接建立阶段一旦连接完成便不再起作用而CURLOPT_TIMEOUT_MS是覆盖全程的总超时。三者在 libcurl 内部共用setopt_set_timeout_ms()做参数校验但作用于完全不同的阶段CURLOPT_ACCEPTTIMEOUT_MS只关心数据连接回连这一瞬。可用性、返回值与编译前提可用性该选项自 libcurl7.24.0起引入见原文档 front-matter 的Added-in字段。协议范围仅适用于FTP含 FTPS 的主动模式场景对其他协议无效。编译前提该选项的注册与存储字段都包裹在#ifndef CURL_DISABLE_FTP条件编译中lib/setopt.c、lib/urldata.h。也就是说使用-DCURL_DISABLE_FTP裁剪掉 FTP 支持的构建中本选项不存在调用会以CURLE_UNKNOWN_OPTION之类的错误失败。返回值curl_easy_setopt()返回CURLcode。CURLE_OK (0)表示设置成功非零表示出错如传入负数得到CURLE_BAD_FUNCTION_ARGUMENT。具体错误码含义参见 docs/libcurl/libcurl-errors.md。命令行对照curl 工具中的对应能力在 curl 命令行工具中主动模式由--ftp-port-P开关启用例如curl --ftp-port - --accept-timeout 5 ftp://example.com/path/file不过需要说明--accept-timeout对应的是命令行工具另一套等待服务器响应的超时语义而命令行工具本身并没有直接暴露CURLOPT_ACCEPTTIMEOUT_MS的独立参数。要在命令行场景精确控制主动模式回连超时通常通过全局--connect-timeout与总时长--max-time间接约束或直接使用 libcurl API 编写程序如上文示例。这是使用该选项时最容易混淆的一点务必区分。实战建议只与CURLOPT_FTPPORT组合使用单独设置本选项不会启用主动模式也不会产生任何效果。考虑 NAT / 防火墙环境主动模式要求服务器能反向连回客户端这在客户端处于 NAT 或防火墙后时常失败。此时应把回连超时调短如 510 秒以便快速失败或改用被动模式libcurl 默认规避。善用默认值多数情况下 60 秒的默认值偏保守若业务对响应时间敏感建议显式设置更小的毫秒值同时留意全局CURLOPT_TIMEOUT_MS会截短本选项的等待上限。检查构建配置如果你的 libcurl 是裁剪版禁用了 FTP该选项不可用代码中应做好错误处理。参考官方示例仓库 docs/examples/ftpuploadresume.c 提供了主动模式 回连超时的完整可运行范例适合作为上手模板。总结CURLOPT_ACCEPTTIMEOUT_MS是 libcurl 为 FTP 主动模式量身定制的等待超时选项它以毫秒为单位、默认 60000ms、负数非法、仅对主动 FTP 生效并与CURLOPT_FTPPORT协同工作。从 lib/ftp.c 的状态机到 lib/cf-socket.c 的过滤器超时计算整条实现链路清晰可查。理解它的生效边界与默认值行为能帮助你在主动 FTP 场景中精确控制等待时长写出更健壮的传输代码。【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考