From dd29622f323ca1148817eb7b257fe456bdf5d2a1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 20 Nov 2023 17:22:40 +0100 Subject: [PATCH] CURLOPT_SERVER_RESPONSE_TIMEOUT_MS: add Proposed-by: Yifei Kong Ref: https://curl.se/mail/lib-2023-11/0023.html Closes #12369 --- docs/libcurl/curl_easy_setopt.3 | 2 + .../opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 | 76 +++++++++++++++++++ docs/libcurl/opts/Makefile.inc | 1 + docs/libcurl/symbols-in-versions | 1 + include/curl/curl.h | 3 + lib/easyoptions.c | 4 +- lib/setopt.c | 11 +++ 7 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 7e7819f64..d4a5dcb5c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -423,6 +423,8 @@ Use PRET. See \fICURLOPT_FTP_USE_PRET(3)\fP Create missing directories on the remote server. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP .IP CURLOPT_SERVER_RESPONSE_TIMEOUT Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP +.IP CURLOPT_SERVER_RESPONSE_TIMEOUT_MS +Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP .IP CURLOPT_FTP_ALTERNATIVE_TO_USER Alternative to USER. See \fICURLOPT_FTP_ALTERNATIVE_TO_USER(3)\fP .IP CURLOPT_FTP_SKIP_PASV_IP diff --git a/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 new file mode 100644 index 000000000..08239b749 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 @@ -0,0 +1,76 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" * SPDX-License-Identifier: curl +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_SERVER_RESPONSE_TIMEOUT_MS 3 "19 Jun 2014" libcurl libcurl +.SH NAME +CURLOPT_SERVER_RESPONSE_TIMEOUT_MS \- time allowed to wait for server response +.SH SYNOPSIS +.nf +#include + +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, + long timeout); +.fi +.SH DESCRIPTION +Pass a long. Causes libcurl to set a \fItimeout\fP period (in milliseconds) +on the amount of time that the server is allowed to take in order to send a +response message for a command before the session is considered dead. While +libcurl is waiting for a response, this value overrides +\fICURLOPT_TIMEOUT(3)\fP. It is recommended that if used in conjunction with +\fICURLOPT_TIMEOUT(3)\fP, you set \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP +to a value smaller than \fICURLOPT_TIMEOUT(3)\fP. + +The maximum accepted value is 2147483648. + +This is the millisecond version of \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP. +.SH DEFAULT +None +.SH PROTOCOLS +FTP, IMAP, POP3, SMTP, and SSH +.SH EXAMPLE +.nf +int main(void) +{ + CURL *curl = curl_easy_init(); + if(curl) { + CURLcode res; + curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/slow.txt"); + /* wait no more than 237 milliseconds */ + curl_easy_setopt(curl, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, 237L); + res = curl_easy_perform(curl); + + curl_easy_cleanup(curl); + } +} +.fi +.SH AVAILABILITY +Added in 8.6.0. +.SH RETURN VALUE +Returns CURLE_OK if supported, and CURLE_UNKNOWN_OPTION if not. Returns +CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value or a value that when +converted to milliseconds is too large. +.SH "SEE ALSO" +.BR CURLOPT_CONNECTTIMEOUT (3), +.BR CURLOPT_LOW_SPEED_LIMIT (3), +.BR CURLOPT_TIMEOUT (3) diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc index 9fe780677..4b581c5be 100644 --- a/docs/libcurl/opts/Makefile.inc +++ b/docs/libcurl/opts/Makefile.inc @@ -332,6 +332,7 @@ man_MANS = \ CURLOPT_SEEKDATA.3 \ CURLOPT_SEEKFUNCTION.3 \ CURLOPT_SERVER_RESPONSE_TIMEOUT.3 \ + CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 \ CURLOPT_SERVICE_NAME.3 \ CURLOPT_SHARE.3 \ CURLOPT_SOCKOPTDATA.3 \ diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 179ba1102..a77a52550 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -801,6 +801,7 @@ CURLOPT_SASL_IR 7.31.0 CURLOPT_SEEKDATA 7.18.0 CURLOPT_SEEKFUNCTION 7.18.0 CURLOPT_SERVER_RESPONSE_TIMEOUT 7.20.0 +CURLOPT_SERVER_RESPONSE_TIMEOUT_MS 8.6.0 CURLOPT_SERVICE_NAME 7.43.0 CURLOPT_SHARE 7.10 CURLOPT_SOCKOPTDATA 7.16.0 diff --git a/include/curl/curl.h b/include/curl/curl.h index ab600b83c..a5b59e026 100644 --- a/include/curl/curl.h +++ b/include/curl/curl.h @@ -2202,6 +2202,9 @@ typedef enum { /* set a specific client IP for HAProxy PROXY protocol header? */ CURLOPT(CURLOPT_HAPROXY_CLIENT_IP, CURLOPTTYPE_STRINGPOINT, 323), + /* millisecond version */ + CURLOPT(CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, CURLOPTTYPE_LONG, 324), + CURLOPT_LASTENTRY /* the last unused */ } CURLoption; diff --git a/lib/easyoptions.c b/lib/easyoptions.c index e69c658b0..da4c6111a 100644 --- a/lib/easyoptions.c +++ b/lib/easyoptions.c @@ -274,6 +274,8 @@ struct curl_easyoption Curl_easyopts[] = { {"SEEKFUNCTION", CURLOPT_SEEKFUNCTION, CURLOT_FUNCTION, 0}, {"SERVER_RESPONSE_TIMEOUT", CURLOPT_SERVER_RESPONSE_TIMEOUT, CURLOT_LONG, 0}, + {"SERVER_RESPONSE_TIMEOUT_MS", CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, + CURLOT_LONG, 0}, {"SERVICE_NAME", CURLOPT_SERVICE_NAME, CURLOT_STRING, 0}, {"SHARE", CURLOPT_SHARE, CURLOT_OBJECT, 0}, {"SOCKOPTDATA", CURLOPT_SOCKOPTDATA, CURLOT_CBPTR, 0}, @@ -373,6 +375,6 @@ struct curl_easyoption Curl_easyopts[] = { */ int Curl_easyopts_check(void) { - return ((CURLOPT_LASTENTRY%10000) != (323 + 1)); + return ((CURLOPT_LASTENTRY%10000) != (324 + 1)); } #endif diff --git a/lib/setopt.c b/lib/setopt.c index a08140cce..460cb32e7 100644 --- a/lib/setopt.c +++ b/lib/setopt.c @@ -366,6 +366,17 @@ CURLcode Curl_vsetopt(struct Curl_easy *data, CURLoption option, va_list param) else return CURLE_BAD_FUNCTION_ARGUMENT; break; + case CURLOPT_SERVER_RESPONSE_TIMEOUT_MS: + /* + * Option that specifies how quickly a server response must be obtained + * before it is considered failure. For pingpong protocols. + */ + arg = va_arg(param, long); + if((arg >= 0) && (arg <= INT_MAX)) + data->set.server_response_timeout = (unsigned int)arg; + else + return CURLE_BAD_FUNCTION_ARGUMENT; + break; #ifndef CURL_DISABLE_TFTP case CURLOPT_TFTP_NO_OPTIONS: /*