libcurl-env.3: first take

1 files changed, 89 insertions, 0 deletions

diff --git a/docs/libcurl/libcurl-env.3 b/docs/libcurl/libcurl-env.3
new file mode 100644
index 000000000..6548cd4aa
--- /dev/null
+++ b/docs/libcurl/libcurl-env.3
@@ -0,0 +1,89 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at https://curl.haxx.se/docs/copyright.html.
+.\" *
+.\" * 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.
+.\" *
+.\" **************************************************************************
+.TH libcurl-env 3 "20 January 2018" "libcurl 7.58.0" "libcurl environment variables"
+.SH NAME
+libcurl-env \- environment variables libcurl understands
+.SH DESCRIPTION
+libcurl reads and understands a set of environment variables that if set will
+control and change behaviors. This is the full list of variables to set and
+description of what they do. Also note that curl, the command line tool,
+supports a set of additional environment variables independently of this.
+.IP "[scheme]_proxy"
+When libcurl is given a URL to use in a transfer, it first extracts the
+"scheme" part from the URL and checks if there is a given proxy set for that
+in its corresponding environment variable. A URL like "http://example.com"
+will hence use the "http_proxy" variable, while a URL like "ftp://example.com"
+will use the "ftp_proxy" variable.
+
+These proxy variables are also checked for in their uppercase versions, except
+the "http_proxy" one which is only used lowercase. Note also that some systems
+actually have a case insensitve handling of environment variables and then of
+course "HTTP_PROXY" will still work...
+.IP ALL_PROXY
+This is a setting to set proxy for all URLs, independently of what scheme is
+being used. Note that the scheme specific variables will override this one if
+set.
+.IP CURL_SSL_BACKEND
+When libcurl is built to support multiple SSL backends, it will select a
+specific backend at first use. If no selection is done by the program using
+libcurl, this variable's selection will be used. It should be set to the full
+SSL backend name to use (case insensitve).
+.IP HOME
+When the netrc feature is used (\fBCURLOPT_NETRC(3)\fP), this variable is
+checked as the primary way to find the "current" home directory in which
+the .netrc file is likely to exist.
+.IP LOGNAME
+User name to use when invoking the ntlm-wb tool, if NTLMUSER wasn't set.
+.IP NO_PROXY
+This has the same functionality as the \fBCURLOPT_NOPROXY(3)\fP option: it
+gives libcurl a comma-separated list of host name patterns for which libcurl
+should not use a proxy.
+.IP NTLMUSER
+User name to use when invoking the ntlm-wb tool.
+.IP SSLKEYLOGFILE
+When set and libcurl runs with a SSL backend that supports this feature,
+libcurl will save SSL secrets into the given file name. Using those SSL
+secrets, other tools (such as Wireshark) can decrypt the SSL communication and
+analyze/view the traffic.
+.IP SSL_DIR
+When libcurl runs with the NSS backends for TLS features, this variable is
+used to find the directory for NSS PKI database instead of the built-in.
+.IP USER
+User name to use when invoking the ntlm-wb tool, if NTLMUSER and LOGNAME
+weren't set.
+.SH "Debug Variables"
+There's a set of variables only recognized and used if libcurl was buillt
+"debug enabled", which should never be true for a library used in production.
+.IP "CURL_GETHOSTNAME"
+Debug-only variable.
+.IP "CURL_FORCETIME"
+Debug-only variable.
+.IP "CURL_ENTROPY"
+Debug-only variable. Used to set a fixed faked value to use instead of a
+proper random number so that functions in libcurl that are otherwise getting
+random outputs can be tested for what they generate.
+.IP "CURL_TRACE"
+Debug-only variable. Used for debugging the lib/ldap implementation.
+.IP "CURL_NTLM_WB_FILE"
+Debug-only variable. Used to set to a debug-version of the ntlm-wb executable.
+.IP "CURL_OPENLDAP_TRACE"
+Debug-only variable. Used for debugging the lib/openldap.c implementation.