Ubuntu Manpage: CURLOPT_NETRC - enable use of .netrc

NAME

       CURLOPT_NETRC - enable use of .netrc

SYNOPSIS

       #include <curl/curl.h>

       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level);

DESCRIPTION

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.

FILE FORMAT

       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 namd 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.

DEFAULT

       CURL_NETRC_IGNORED

PROTOCOLS

       Most

EXAMPLE

       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);
       }

AVAILABILITY

       Always

RETURN VALUE

       Returns CURLE_OK