From: Daniel Stenberg <daniel@haxx.se>
Date: Tue, 31 May 2022 08:56:35 +0000 (+0200)
Subject: CURLOPT_PORT.3: We discourage using this option
X-Git-Tag: curl-7_84_0~112
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b2175acc762eec66c486ed162c2b2628ee7cf60e;p=thirdparty%2Fcurl.git

CURLOPT_PORT.3: We discourage using this option

Closes #8941
---

diff --git a/docs/libcurl/opts/CURLOPT_PORT.3 b/docs/libcurl/opts/CURLOPT_PORT.3
index bc70ba795e..a5a065617d 100644
--- a/docs/libcurl/opts/CURLOPT_PORT.3
+++ b/docs/libcurl/opts/CURLOPT_PORT.3
@@ -30,6 +30,9 @@ CURLOPT_PORT \- remote port number to connect to
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PORT, long number);
 .fi
 .SH DESCRIPTION
+We discourage using this option since it's scope is not obvious and hard to
+predict. Set the preferred port number in the URL instead.
+
 This option sets \fInumber\fP to be the remote port number to connect to,
 instead of the one specified in the URL or the default port for the used
 protocol.
@@ -40,7 +43,8 @@ application to override that.
 While this option accepts a 'long', a port number is usually a 16 bit number
 and therefore using a port number over 65535 will cause a runtime error.
 .SH DEFAULT
-By default this is 0 which makes it not used.
+By default this is 0 which makes it not used. This also makes port number zero
+impossible to set with this API.
 .SH PROTOCOLS
 Used for all protocols that speak to a port number.
 .SH EXAMPLE