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