repo/core/curl/files/CURLOPT_NETRC.3

.\" generated by cd2nroff 0.1 from CURLOPT_NETRC.md
.TH CURLOPT_NETRC 3 "2024-07-29" libcurl
.SH NAME
CURLOPT_NETRC \- enable use of .netrc
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level);
.fi
.SH DESCRIPTION
This parameter controls the preference \fIlevel\fP of libcurl between using
usernames and passwords from your \fI~/.netrc\fP file, relative to usernames and
passwords in the URL supplied with \fICURLOPT_URL(3)\fP.

On Windows, libcurl primarily checks for \fI.netrc\fP in \fI%HOME%\fP. If \fI%HOME%\fP is
not set on Windows, libcurl falls back to \fI%USERPROFILE%\fP. If the file does
not exist, it falls back to check if there is instead a file named \fI_netrc\fP \-
using an underscore instead of period.

You can also tell libcurl a different filename to use with
\fICURLOPT_NETRC_FILE(3)\fP.

libcurl uses a username (and supplied or prompted password) supplied with
\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP in preference to any of
the options controlled by this parameter.

Only machine name, username 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.

\fIlevel\fP is a long that should be set to one of the values described below.
.IP "CURL_NETRC_IGNORED (0)"
libcurl ignores the \fI.netrc\fP file. This is the default.
.IP "CURL_NETRC_OPTIONAL (1)"
The use of the \fI.netrc\fP file is optional, and information in the URL is to
be preferred. The file is scanned for the host and username (to find the
password only) or for the host only, to find the first username and password
after that \fImachine\fP, which ever information is not specified.
.IP "CURL_NETRC_REQUIRED (2)"
The use of the \fI.netrc\fP file is required, and any credential information
present in the URL is ignored. The file is scanned for the host and username
(to find the password only) or for the host only, to find the first username
and password after that \fImachine\fP, which ever information is not
specified.
.SH FILE FORMAT
The \fB.netrc\fP 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 ", n,
r, and t. Quoted strings are the only way a space character can be used in
a username or password.
.IP "machine \<name\>"
Provides credentials for a host called \fBname\fP. libcurl searches the .netrc
file for a machine token that matches the hostname 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.
.IP 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:

.nf
default login anonymous password user@domain
.fi
.IP "login \<name\>"
The username string for the remote machine.
.IP "password \<secret\>"
Supply a password. If this token is present, curl supplies 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.
.IP "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 properly skips every definition
done with "macdef" that it finds.
.SH DEFAULT
CURL_NETRC_IGNORED
.SH PROTOCOLS
This functionality affects all supported protocols
.SH EXAMPLE
.nf
int main(void)
{
  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);
  }
}
.fi
.SH AVAILABILITY
Added in curl 7.1
.SH RETURN VALUE
Returns CURLE_OK
.SH SEE ALSO
.BR CURLOPT_NETRC_FILE (3),
.BR CURLOPT_USERNAME (3),
.BR CURLOPT_USERPWD (3)