curl--connect-timeout详解限制连接阶段的超时上限【免费下载链接】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本文围绕 curl 命令行工具的--connect-timeout选项展开讲解它在当前 curl 仓库docs/cmdline-opts/connect-timeout.md中定义的行为边界、可配置格式并结合 lib/setopt.c、lib/multi.c、lib/connect.c 等源码说明其从命令行参数到内部超时定时器的完整链路。读完本文你将掌握如何精确控制 curl 的连接耗时上限、它与总超时--max-time的区别以及 libcurl 编程接口中的对应设置方式。一、选项概览它管住的是哪一段耗时--connect-timeout用于设置“连接阶段允许花费的最大时间”单位是秒。它是 curl 的全局长选项对应的参数帮助文本为 “Maximum time allowed to connect”最大允许连接时间分类属于 connection timeout自 curl 7.7 起加入属于单值选项Multi: single同一命令行中只允许出现一次。其核心语义有两个要点也是与--max-time最本质的区别只约束连接阶段该选项只限制“建立连接”的过程。一旦连上即退出约束范围如果 curl 在给定时间内完成了连接它就会继续执行后续的数据传输只有在规定时间内未能完成连接时curl 才会放弃退出。这与--max-time全请求总时长上限形成互补。后者的完整定义见 docs/cmdline-opts/max-time.md它限制的是包括连接、发送、接收在内的整次操作的总时长。二、“连接阶段”到底包含哪些步骤原文档明确给出了连接阶段结束的判定标准当 DNS 解析以及所请求的 TCP、TLS 或 QUIC 握手全部完成时连接阶段即视为完成。也就是说--connect-timeout的计时覆盖范围包括DNS 解析把主机名解析为 IP 地址所花的时间TCP 握手三次握手建立 TCP 连接的耗时TLS 握手如果使用https://、ftps://等需要 TLS 的协议则包含 TLS 协商过程QUIC 握手针对 HTTP/3基于 QUIC等场景同样包含在内。只要上述任一环节超过限制整体连接即被判定为超时。从当前仓库的源码实现看连接过程中剩余时间的计算发生在 lib/connect.c 的timeleft_now_ms()中在处于“连接中”Curl_is_connecting状态时代码以配置的连接超时值为基准减去自TIMER_STARTSINGLE单次连接尝试的起始计时点以来已流逝的时间得到剩余可用的毫秒数。这与“连接阶段从尝试开始就进入倒计时”的文档语义是吻合的。三、命令行用法与示例3.1 基础用法直接传入秒数即可curl --connect-timeout 20 https://example.com/含义curl 在尝试连接example.com时从发起连接到完成连接最多允许 20 秒超时则退出。3.2 小数秒自 7.32.0 起支持从 curl 7.32.0 开始该选项接受小数值可以更精细地控制超时粒度curl --connect-timeout 3.14 https://example.com/注意小数分隔符必须是英文句点.。原文档特别强调无论本地区域设置中使用的是什么小数点符号例如某些地区习惯用逗号,这里都必须用点号.作为分隔符否则参数将无法被正确解析。从参数解析实现看命令行把该选项声明为ARG_SECS类型见 src/tool_getparam.c即“秒”类型的参数解析时经由secs2ms将可能含小数的秒换算为毫秒整数后存入配置如 src/tool_getparam.c 所示最终落入config-connecttimeout_ms。3.3 超时后的表现当连接超时被触发时本次操作会以“操作超时”类错误终止。在 include/curl/curl.h 中定义了对应的错误码CURLE_OPERATION_TIMEDOUT, /* 28 - the timeout time was reached */即 curl 命令行以退出码 28 结束本次操作。四、源码链路从命令行参数到连接超时定时器为了让--connect-timeout真正生效当前仓库经历了下面这条清晰的调用链可用于理解其底层原理。4.1 命令行解析层在 src/tool_getparam.c 中选项表注册了{connect-timeout, ARG_SECS, , C_CONNECT_TIMEOUT},当用户给出该参数时进入case C_CONNECT_TIMEOUT分支src/tool_getparam.c把换算后的毫秒值保存到config-connecttimeout_ms。4.2 传递给 libcurl 的 setopt 层命令行工具最终会把该值映射到 libcurl 的传输选项上。在 lib/setopt.c 中可以看到两个相关选项的处理CURLOPT_CONNECTTIMEOUT以秒为单位的连接超时CURLOPT_CONNECTTIMEOUT_MS以毫秒为单位的连接超时精度更高。两者最终都写入同一份配置字段。在 lib/urldata.h 中该字段定义为timediff_t connecttimeout; /* ms, 0 means default timeout */单位为毫秒值为 0 表示“使用默认超时”而不施加显式限制。4.3 连接状态机中的到期调度在 lib/multi.c 中当connecttimeout被显式设置非 0时libcurl 会通过Curl_expire注册一个EXPIRE_CONNECTTIMEOUT到期事件if(data-set.connecttimeout) Curl_expire(data,>#define DEFAULT_CONNECT_TIMEOUT 300000 /* milliseconds five minutes */即内部默认兜底为 300000 毫秒5 分钟。也就是说即使不显式配置连接阶段在内核计时层面也存在一个较大的默认上限作为保护显式配置的值则是更严格的、用户可控的约束。五、与--max-time的配合使用--connect-timeout与--max-time常被一起使用二者互为补充选项限制范围典型场景--connect-timeout仅连接阶段DNS TCP/TLS/QUIC 握手快速失败连不上就尽早退出不长时间干等--max-time整次操作总时长兜底限制整体耗时上限防止传输阶段无限拉长推荐做法是在脚本与自动化任务中同时给出两个值例如curl --connect-timeout 10 --max-time 60 https://example.com/large-file其效果是连接超过 10 秒即放弃即使连接成功整次下载也不允许超过 60 秒。在命令行帮助系统中connect-timeout 手册 的 See-also 里也把max-time列为关联选项反过来max-time 手册 同样将connect-timeout列为关联选项二者在设计上就是配套使用的。六、编程接口对应libcurl 开发者如何设置如果使用 libcurl 进行编程而不是调用命令行可以用下面两个选项达到同样效果对应实现位于 lib/setopt.c/* 以秒为单位最低 1 秒粒度 */ curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 20L); /* 以毫秒为单位支持亚秒级精度如 3.14 秒 3140ms */ curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT_MS, 3140L);命令行版本本质上是把--connect-timeout seconds换算成毫秒后通过CURLOPT_CONNECTTIMEOUT_MS送入 libcurl因此二者底层语义完全一致均只约束 DNS/TCP/TLS/QUIC 的连接建立过程不影响建立连接之后的数据传输阶段。七、实践要点小结优先设置“连接超时 总超时”双保险--connect-timeout解决“连不上还要傻等”的问题--max-time解决“传输太慢拖死任务”的问题小数秒必须用点号例如--connect-timeout 0.5表示 500 毫秒但写法上不要受本地区域小数点习惯影响它是单值选项同一命令行只应出现一次配合--max-time、--retry-max-time等选项可实现更完整的超时策略面向可编程复用的场景命令行对应的 libcurl 选项为CURLOPT_CONNECTTIMEOUT与精度更高的CURLOPT_CONNECTTIMEOUT_MS二者的字段在 lib/urldata.h 中以毫秒统一存储触发后的可观测结果超时将以退出码 28CURLE_OPERATION_TIMEDOUT见 include/curl/curl.h结束操作脚本中可据此做重试或告警分流。【免费下载链接】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 `--connect-timeout` 详解：限制连接阶段的超时上限
curl--connect-timeout详解限制连接阶段的超时上限【免费下载链接】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本文围绕 curl 命令行工具的--connect-timeout选项展开讲解它在当前 curl 仓库docs/cmdline-opts/connect-timeout.md中定义的行为边界、可配置格式并结合 lib/setopt.c、lib/multi.c、lib/connect.c 等源码说明其从命令行参数到内部超时定时器的完整链路。读完本文你将掌握如何精确控制 curl 的连接耗时上限、它与总超时--max-time的区别以及 libcurl 编程接口中的对应设置方式。一、选项概览它管住的是哪一段耗时--connect-timeout用于设置“连接阶段允许花费的最大时间”单位是秒。它是 curl 的全局长选项对应的参数帮助文本为 “Maximum time allowed to connect”最大允许连接时间分类属于 connection timeout自 curl 7.7 起加入属于单值选项Multi: single同一命令行中只允许出现一次。其核心语义有两个要点也是与--max-time最本质的区别只约束连接阶段该选项只限制“建立连接”的过程。一旦连上即退出约束范围如果 curl 在给定时间内完成了连接它就会继续执行后续的数据传输只有在规定时间内未能完成连接时curl 才会放弃退出。这与--max-time全请求总时长上限形成互补。后者的完整定义见 docs/cmdline-opts/max-time.md它限制的是包括连接、发送、接收在内的整次操作的总时长。二、“连接阶段”到底包含哪些步骤原文档明确给出了连接阶段结束的判定标准当 DNS 解析以及所请求的 TCP、TLS 或 QUIC 握手全部完成时连接阶段即视为完成。也就是说--connect-timeout的计时覆盖范围包括DNS 解析把主机名解析为 IP 地址所花的时间TCP 握手三次握手建立 TCP 连接的耗时TLS 握手如果使用https://、ftps://等需要 TLS 的协议则包含 TLS 协商过程QUIC 握手针对 HTTP/3基于 QUIC等场景同样包含在内。只要上述任一环节超过限制整体连接即被判定为超时。从当前仓库的源码实现看连接过程中剩余时间的计算发生在 lib/connect.c 的timeleft_now_ms()中在处于“连接中”Curl_is_connecting状态时代码以配置的连接超时值为基准减去自TIMER_STARTSINGLE单次连接尝试的起始计时点以来已流逝的时间得到剩余可用的毫秒数。这与“连接阶段从尝试开始就进入倒计时”的文档语义是吻合的。三、命令行用法与示例3.1 基础用法直接传入秒数即可curl --connect-timeout 20 https://example.com/含义curl 在尝试连接example.com时从发起连接到完成连接最多允许 20 秒超时则退出。3.2 小数秒自 7.32.0 起支持从 curl 7.32.0 开始该选项接受小数值可以更精细地控制超时粒度curl --connect-timeout 3.14 https://example.com/注意小数分隔符必须是英文句点.。原文档特别强调无论本地区域设置中使用的是什么小数点符号例如某些地区习惯用逗号,这里都必须用点号.作为分隔符否则参数将无法被正确解析。从参数解析实现看命令行把该选项声明为ARG_SECS类型见 src/tool_getparam.c即“秒”类型的参数解析时经由secs2ms将可能含小数的秒换算为毫秒整数后存入配置如 src/tool_getparam.c 所示最终落入config-connecttimeout_ms。3.3 超时后的表现当连接超时被触发时本次操作会以“操作超时”类错误终止。在 include/curl/curl.h 中定义了对应的错误码CURLE_OPERATION_TIMEDOUT, /* 28 - the timeout time was reached */即 curl 命令行以退出码 28 结束本次操作。四、源码链路从命令行参数到连接超时定时器为了让--connect-timeout真正生效当前仓库经历了下面这条清晰的调用链可用于理解其底层原理。4.1 命令行解析层在 src/tool_getparam.c 中选项表注册了{connect-timeout, ARG_SECS, , C_CONNECT_TIMEOUT},当用户给出该参数时进入case C_CONNECT_TIMEOUT分支src/tool_getparam.c把换算后的毫秒值保存到config-connecttimeout_ms。4.2 传递给 libcurl 的 setopt 层命令行工具最终会把该值映射到 libcurl 的传输选项上。在 lib/setopt.c 中可以看到两个相关选项的处理CURLOPT_CONNECTTIMEOUT以秒为单位的连接超时CURLOPT_CONNECTTIMEOUT_MS以毫秒为单位的连接超时精度更高。两者最终都写入同一份配置字段。在 lib/urldata.h 中该字段定义为timediff_t connecttimeout; /* ms, 0 means default timeout */单位为毫秒值为 0 表示“使用默认超时”而不施加显式限制。4.3 连接状态机中的到期调度在 lib/multi.c 中当connecttimeout被显式设置非 0时libcurl 会通过Curl_expire注册一个EXPIRE_CONNECTTIMEOUT到期事件if(data-set.connecttimeout) Curl_expire(data,>#define DEFAULT_CONNECT_TIMEOUT 300000 /* milliseconds five minutes */即内部默认兜底为 300000 毫秒5 分钟。也就是说即使不显式配置连接阶段在内核计时层面也存在一个较大的默认上限作为保护显式配置的值则是更严格的、用户可控的约束。五、与--max-time的配合使用--connect-timeout与--max-time常被一起使用二者互为补充选项限制范围典型场景--connect-timeout仅连接阶段DNS TCP/TLS/QUIC 握手快速失败连不上就尽早退出不长时间干等--max-time整次操作总时长兜底限制整体耗时上限防止传输阶段无限拉长推荐做法是在脚本与自动化任务中同时给出两个值例如curl --connect-timeout 10 --max-time 60 https://example.com/large-file其效果是连接超过 10 秒即放弃即使连接成功整次下载也不允许超过 60 秒。在命令行帮助系统中connect-timeout 手册 的 See-also 里也把max-time列为关联选项反过来max-time 手册 同样将connect-timeout列为关联选项二者在设计上就是配套使用的。六、编程接口对应libcurl 开发者如何设置如果使用 libcurl 进行编程而不是调用命令行可以用下面两个选项达到同样效果对应实现位于 lib/setopt.c/* 以秒为单位最低 1 秒粒度 */ curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 20L); /* 以毫秒为单位支持亚秒级精度如 3.14 秒 3140ms */ curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT_MS, 3140L);命令行版本本质上是把--connect-timeout seconds换算成毫秒后通过CURLOPT_CONNECTTIMEOUT_MS送入 libcurl因此二者底层语义完全一致均只约束 DNS/TCP/TLS/QUIC 的连接建立过程不影响建立连接之后的数据传输阶段。七、实践要点小结优先设置“连接超时 总超时”双保险--connect-timeout解决“连不上还要傻等”的问题--max-time解决“传输太慢拖死任务”的问题小数秒必须用点号例如--connect-timeout 0.5表示 500 毫秒但写法上不要受本地区域小数点习惯影响它是单值选项同一命令行只应出现一次配合--max-time、--retry-max-time等选项可实现更完整的超时策略面向可编程复用的场景命令行对应的 libcurl 选项为CURLOPT_CONNECTTIMEOUT与精度更高的CURLOPT_CONNECTTIMEOUT_MS二者的字段在 lib/urldata.h 中以毫秒统一存储触发后的可观测结果超时将以退出码 28CURLE_OPERATION_TIMEDOUT见 include/curl/curl.h结束操作脚本中可据此做重试或告警分流。【免费下载链接】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），仅供参考