mirror/curl
2
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2024-12-27 06:59:43 +08:00
Code Issues Packages Projects Releases Wiki Activity
85ce7f8070
curl/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

74 lines
2.7 KiB
Groff
Raw Normal View History

resolve: add CURLOPT_DNS_SHUFFLE_ADDRESSES This patch adds CURLOPT_DNS_SHUFFLE_ADDRESSES to explicitly request shuffling of IP addresses returned for a hostname when there is more than one. This is useful when the application knows that a round robin approach is appropriate and is willing to accept the consequences of potentially discarding some preference order returned by the system's implementation. Closes #1694
2018-03-18 03:10:04 +08:00
.\" **************************************************************************
.\" * _ _ ____ _
.\" * Project ___| | | | _ \| |
.\" * / __| | | | |_) | |
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
copyright: update all copyright lines and remove year ranges - they are mostly pointless in all major jurisdictions - many big corporations and projects already don't use them - saves us from pointless churn - git keeps history for us - the year range is kept in COPYING checksrc is updated to allow non-year using copyright statements Closes #10205
2023-01-02 20:51:48 +08:00
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
resolve: add CURLOPT_DNS_SHUFFLE_ADDRESSES This patch adds CURLOPT_DNS_SHUFFLE_ADDRESSES to explicitly request shuffling of IP addresses returned for a hostname when there is more than one. This is useful when the application knows that a round robin approach is appropriate and is willing to accept the consequences of potentially discarding some preference order returned by the system's implementation. Closes #1694
2018-03-18 03:10:04 +08:00
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
curl.se: new home Closes #6172
2020-11-04 21:02:01 +08:00
.\" * are also available at https://curl.se/docs/copyright.html.
resolve: add CURLOPT_DNS_SHUFFLE_ADDRESSES This patch adds CURLOPT_DNS_SHUFFLE_ADDRESSES to explicitly request shuffling of IP addresses returned for a hostname when there is more than one. This is useful when the application knows that a round robin approach is appropriate and is willing to accept the consequences of potentially discarding some preference order returned by the system's implementation. Closes #1694
2018-03-18 03:10:04 +08:00
.\" *
.\" * 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
copyright: make repository REUSE compliant Add licensing and copyright information for all files in this repository. This either happens in the file itself as a comment header or in the file `.reuse/dep5`. This commit also adds a Github workflow to check pull requests and adapts copyright.pl to the changes. Closes #8869
2022-05-17 17:16:50 +08:00
.\" *
resolve: add CURLOPT_DNS_SHUFFLE_ADDRESSES This patch adds CURLOPT_DNS_SHUFFLE_ADDRESSES to explicitly request shuffling of IP addresses returned for a hostname when there is more than one. This is useful when the application knows that a round robin approach is appropriate and is willing to accept the consequences of potentially discarding some preference order returned by the system's implementation. Closes #1694
2018-03-18 03:10:04 +08:00
.\" **************************************************************************
.\"
man pages: simplify the .TH sections - remove the version numbers - simplify the texts The date and version number will be put there for releases when maketgz runs the updatemanpages.pl script. Closes #11029
2023-04-26 14:58:35 +08:00
.TH CURLOPT_DNS_SHUFFLE_ADDRESSES 3 "3 March 2018" libcurl libcurl
resolve: add CURLOPT_DNS_SHUFFLE_ADDRESSES This patch adds CURLOPT_DNS_SHUFFLE_ADDRESSES to explicitly request shuffling of IP addresses returned for a hostname when there is more than one. This is useful when the application knows that a round robin approach is appropriate and is willing to accept the consequences of potentially discarding some preference order returned by the system's implementation. Closes #1694
2018-03-18 03:10:04 +08:00
.SH NAME
opts docs: unify phrasing in NAME header - avoid writing "set ..." or "enable/disable ..." or "specify ..." *All* options for curl_easy_setopt() are about setting or enabling things and most of the existing options didn't use that way of description. - start with lowercase letter, unless abbreviation. For consistency. - Some additional touch-ups Closes #7688
2021-09-09 04:55:58 +08:00
CURLOPT_DNS_SHUFFLE_ADDRESSES \- shuffle IP addresses for hostname
resolve: add CURLOPT_DNS_SHUFFLE_ADDRESSES This patch adds CURLOPT_DNS_SHUFFLE_ADDRESSES to explicitly request shuffling of IP addresses returned for a hostname when there is more than one. This is useful when the application knows that a round robin approach is appropriate and is willing to accept the consequences of potentially discarding some preference order returned by the system's implementation. Closes #1694
2018-03-18 03:10:04 +08:00
.SH SYNOPSIS
.nf
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SHUFFLE_ADDRESSES, long onoff);
.fi
.SH DESCRIPTION
docs: rewrite to present tense ... instead of using future tense. + numerous cleanups and improvements + stick to "reuse" not "re-use" + fewer contractions Closes #11713
2023-08-22 23:40:39 +08:00
Pass a long set to 1 to enable this option.
resolve: add CURLOPT_DNS_SHUFFLE_ADDRESSES This patch adds CURLOPT_DNS_SHUFFLE_ADDRESSES to explicitly request shuffling of IP addresses returned for a hostname when there is more than one. This is useful when the application knows that a round robin approach is appropriate and is willing to accept the consequences of potentially discarding some preference order returned by the system's implementation. Closes #1694
2018-03-18 03:10:04 +08:00
docs: rewrite to present tense ... instead of using future tense. + numerous cleanups and improvements + stick to "reuse" not "re-use" + fewer contractions Closes #11713
2023-08-22 23:40:39 +08:00
When a name is resolved and more than one IP address is returned, this
function shuffles the order of all returned addresses so that they are used in
a random order. This is similar to the ordering behavior of the legacy
gethostbyname function which is no longer used on most platforms.
Addresses are not reshuffled if name resolution is completed using the DNS
cache. \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP can be used together with this
resolve: add CURLOPT_DNS_SHUFFLE_ADDRESSES This patch adds CURLOPT_DNS_SHUFFLE_ADDRESSES to explicitly request shuffling of IP addresses returned for a hostname when there is more than one. This is useful when the application knows that a round robin approach is appropriate and is willing to accept the consequences of potentially discarding some preference order returned by the system's implementation. Closes #1694
2018-03-18 03:10:04 +08:00
option to reduce DNS cache timeout or disable caching entirely if frequent
reshuffling is needed.
docs: rewrite to present tense ... instead of using future tense. + numerous cleanups and improvements + stick to "reuse" not "re-use" + fewer contractions Closes #11713
2023-08-22 23:40:39 +08:00
Since the addresses returned are randomly reordered, the order is not in
accordance with RFC 3484 or any other deterministic order that may be
resolve: add CURLOPT_DNS_SHUFFLE_ADDRESSES This patch adds CURLOPT_DNS_SHUFFLE_ADDRESSES to explicitly request shuffling of IP addresses returned for a hostname when there is more than one. This is useful when the application knows that a round robin approach is appropriate and is willing to accept the consequences of potentially discarding some preference order returned by the system's implementation. Closes #1694
2018-03-18 03:10:04 +08:00
generated by the system's name resolution implementation. This may have
performance impacts and may cause IPv4 to be used before IPv6 or vice versa.
.SH DEFAULT
0 (disabled)
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_DNS_SHUFFLE_ADDRESSES, 1L);
curl_easy_perform(curl);
/* always cleanup */
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.60.0
.SH RETURN VALUE
CURLE_OK or an error such as CURLE_UNKNOWN_OPTION.
.SH "SEE ALSO"
.BR CURLOPT_DNS_CACHE_TIMEOUT "(3), " CURLOPT_IPRESOLVE "(3), "
Reference in New Issue Copy Permalink