From: Daniel Stenberg <daniel@haxx.se>
Date: Tue, 4 Jun 2024 22:06:28 +0000 (+0200)
Subject: cmdline-opts/interface.md: expand the documentation
X-Git-Tag: curl-8_9_0~296
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=68680ba544a520e5ff493f47523de063b701fe88;p=thirdparty%2Fcurl.git

cmdline-opts/interface.md: expand the documentation

Explain the syntax it supports.

Closes #13882
---

diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words
index 9d96c35782..87b010ad7b 100644
--- a/.github/scripts/spellcheck.words
+++ b/.github/scripts/spellcheck.words
@@ -119,10 +119,10 @@ CMake
 cmake
 CMake's
 cmake's
-CNAME
-CNAMEs
 CMakeLists
 CNA
+CNAME
+CNAMEs
 CodeQL
 codeql
 CODESET
@@ -209,9 +209,9 @@ EBCDIC
 ECC
 ECDHE
 ECH
-ecl
 ECHConfig
 ECHConfigList
+ecl
 ECONNREFUSED
 eCOS
 EFnet
@@ -358,6 +358,7 @@ ifdef
 ifdefed
 Ifdefs
 ifdefs
+ifhost
 IIS
 ILE
 Illumos
diff --git a/docs/cmdline-opts/interface.md b/docs/cmdline-opts/interface.md
index c938fd2717..539e39272b 100644
--- a/docs/cmdline-opts/interface.md
+++ b/docs/cmdline-opts/interface.md
@@ -3,7 +3,7 @@ c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
 SPDX-License-Identifier: curl
 Long: interface
 Arg: <name>
-Help: Use network INTERFACE (or address)
+Help: Use network interface
 Category: connection
 Added: 7.3
 Multi: single
@@ -11,15 +11,41 @@ See-also:
   - dns-interface
 Example:
   - --interface eth0 $URL
+  - --interface "host!10.0.0.1" $URL
+  - --interface "if!enp3s0" $URL
 ---
 
 # `--interface`
 
-Perform an operation using a specified interface. You can enter interface
-name, IP address or hostname. An example could look like:
+Perform the operation using a specified interface. You can enter interface
+name, IP address or hostname. If you prefer to be specific, you can use the
+following special syntax:
 
-    curl --interface eth0:1 https://www.example.com/
+## if!<name>
 
-On Linux it can be used to specify a **VRF**, but the binary needs to either
-have **CAP_NET_RAW** or to be run as root. More information about Linux
-**VRF**: https://www.kernel.org/doc/Documentation/networking/vrf.txt
+Interface name. If the provided name does not match an existing interface,
+curl returns with error 45.
+
+## host!<name>
+
+IP address or hostname.
+
+## ifhost!<interface>!<host>
+
+Interface name and IP address or hostname. This syntax requires libcurl 8.9.0
+or later.
+
+If the provided name does not match an existing interface, curl returns with
+error 45.
+
+##
+
+curl does not support using network interface names for this option on
+Windows.
+
+That name resolve operation if a hostname is provided does **not** use
+DNS-over-HTTPS even if --doh-url is set.
+
+On Linux this option can be used to specify a **VRF** (Virtual Routing and
+Forwarding) device, but the binary then needs to either have the
+**CAP_NET_RAW** capability set or to be run as root.
diff --git a/src/tool_listhelp.c b/src/tool_listhelp.c
index 8429322045..593ae031af 100644
--- a/src/tool_listhelp.c
+++ b/src/tool_listhelp.c
@@ -304,7 +304,7 @@ const struct helptxt helptext[] = {
    "Allow insecure server connections",
    CURLHELP_TLS | CURLHELP_SFTP | CURLHELP_SCP},
   {"    --interface <name>",
-   "Use network INTERFACE (or address)",
+   "Use network interface",
    CURLHELP_CONNECTION},
   {"    --ipfs-gateway <URL>",
    "Gateway for IPFS",