CURLOPT_NETRC - enable use of .netrc
#include <curl/curl.h>
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level);
This parameter controls the preference
level of libcurl between using
user names and passwords from your
~/.netrc file, relative to user
names and passwords in the URL supplied with
CURLOPT_URL(3).
On Windows, libcurl will use the file as
%HOME%/_netrc. If
%HOME%
is not set on Windows, libcurl falls back to
%USERPROFILE%.
You can also tell libcurl a different file name to use with
CURLOPT_NETRC_FILE(3).
libcurl uses a user name (and supplied or prompted password) supplied with
CURLOPT_USERPWD(3) or
CURLOPT_USERNAME(3) in preference to any
of the options controlled by this parameter.
Only machine name, user name and password are taken into account (init macros
and similar things are not supported).
libcurl does not verify that the file has the correct properties set (as the
standard Unix ftp client does). It should only be readable by user.
level is a long that should be set to one of the values described below.
- CURL_NETRC_IGNORED (0)
- The library will ignore the .netrc file. This is the
default.
- CURL_NETRC_OPTIONAL (1)
- The use of the .netrc file is optional, and
information in the URL is to be preferred. The file will be scanned for
the host and user name (to find the password only) or for the host only,
to find the first user name and password after that machine, which
ever information is not specified.
- CURL_NETRC_REQUIRED (2)
- The use of the .netrc file is required, and any
credential information present in the URL is ignored. The file will be
scanned for the host and user name (to find the password only) or for the
host only, to find the first user name and password after that
machine, which ever information is not specified.
The
.netrc file format is simple: you specify lines with a machine name
and follow the login and password that are associated with that machine.
Each field is provided as a sequence of letters that ends with a space or
newline. Starting in 7.84.0, libcurl also supports quoted strings. They start
and end with double quotes and support the escaped special letters \ \r, and
\t. Quoted strings are the only way a space character can be used in a user
name or password.
- machine <name>
- Provides credentials for a host called name. libcurl
searches the .netrc file for a machine token that matches the host name
specified in the URL. Once a match is made, the subsequent tokens are
processed, stopping when the end of file is reached or another
"machine" is encountered.
- default
- This is the same as "machine" name except that
default matches any name. There can be only one default token, and it must
be after all machine tokens. To provide a default anonymous login for
hosts that are not otherwise matched, add a line similar to this in the
end:
default login anonymous password user@domain
- login <name>
- The user name string for the remote machine.
- password <secret>
- Supply a password. If this token is present, curl will
supply the specified string if the remote server requires a password as
part of the login process. Note that if this token is present in the
.netrc file you really should make sure the file is not readable by anyone
besides the user.
- macdef <name>
- Define a macro. This feature is not supported by libcurl.
In order for the rest of the .netrc to still work fine, libcurl will
properly skip every definition done with "macdef" that it
finds.
CURL_NETRC_IGNORED
Most
CURL *curl = curl_easy_init();
if(curl) {
CURLcode ret;
curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/");
curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL);
ret = curl_easy_perform(curl);
}
Always
Returns CURLE_OK
CURLOPT_USERPWD(3),
CURLOPT_USERNAME(3),
CURLOPT_NETRC_FILE(3),