Provided by: libcurl4-doc_8.5.0-2ubuntu10.6_all bug

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 uses 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)
              libcurl ignores 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 is
              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 is 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
       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 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.

       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.

DEFAULT

       CURL_NETRC_IGNORED

PROTOCOLS

       Most

EXAMPLE

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

AVAILABILITY

       Always

RETURN VALUE

       Returns CURLE_OK

SEE ALSO

       CURLOPT_USERPWD(3), CURLOPT_USERNAME(3), CURLOPT_NETRC_FILE(3)

ibcurl 8.5.0                                    December 04, 2023                               CURLOPT_NETRC(3)