1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_INTERFACE 5Section: 3 6Source: libcurl 7Protocol: 8 - All 9See-also: 10 - CURLOPT_SOCKOPTFUNCTION (3) 11 - CURLOPT_TCP_NODELAY (3) 12 - CURLOPT_LOCALPORT (3) 13Added-in: 7.3 14--- 15 16# NAME 17 18CURLOPT_INTERFACE - source interface for outgoing traffic 19 20# SYNOPSIS 21 22~~~c 23#include <curl/curl.h> 24 25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_INTERFACE, char *interface); 26~~~ 27 28# DESCRIPTION 29 30Pass a char pointer as parameter. This sets the *interface* name to use as 31outgoing network interface. The name can be an interface name, an IP address, 32or a hostname. If you prefer one of these, you can use the following special 33prefixes: 34 35* `if!\<name\>` - Interface name 36* `host!\<name\>` - IP address or hostname 37* `ifhost!\<interface\>!\<host\>` - Interface name and IP address or hostname 38 39If `if!` or `ifhost!` is specified but the parameter does not match an existing 40interface, *CURLE_INTERFACE_FAILED* is returned from the libcurl function used 41to perform the transfer. 42 43libcurl does not support using network interface names for this option on 44Windows. 45 46We strongly advise against specifying the interface with a hostname, as it 47causes libcurl to do a blocking name resolve call to retrieve the IP address. 48That name resolve operation does **not** use DNS-over-HTTPS even if 49CURLOPT_DOH_URL(3) is set. 50 51The application does not have to keep the string around after setting this 52option. 53 54Using this option multiple times makes the last set string override the 55previous ones. Set it to NULL to disable its use again. 56 57# DEFAULT 58 59NULL, use whatever the TCP stack finds suitable 60 61# %PROTOCOLS% 62 63# EXAMPLE 64 65~~~c 66int main(void) 67{ 68 CURL *curl = curl_easy_init(); 69 if(curl) { 70 CURLcode res; 71 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); 72 73 curl_easy_setopt(curl, CURLOPT_INTERFACE, "eth0"); 74 75 res = curl_easy_perform(curl); 76 77 curl_easy_cleanup(curl); 78 } 79} 80~~~ 81 82# HISTORY 83 84The `if!` and `host!` syntax was added in 7.24.0. 85 86The `ifhost!` syntax was added in 8.9.0. 87 88# %AVAILABILITY% 89 90# RETURN VALUE 91 92Returns CURLE_OK on success or 93CURLE_OUT_OF_MEMORY if there was insufficient heap space. 94
