CURLOPT_NETRC(3)

1CURLOPT_NETRC(3)           curl_easy_setopt options           CURLOPT_NETRC(3)
2
3
4

NAME

6       CURLOPT_NETRC - enable use of .netrc
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level);
12

DESCRIPTION

14       This  parameter  controls the preference level of libcurl between using
15       user names and passwords from your  ~/.netrc  file,  relative  to  user
16       names and passwords in the URL supplied with CURLOPT_URL(3).
17
18       On  Windows,  libcurl  will use the file as %HOME%/_netrc. If %HOME% is
19       not set on Windows, libcurl falls back to %USERPROFILE%.
20
21       You can also tell libcurl a  different  file  name  to  use  with  CUR‐
22       LOPT_NETRC_FILE(3).
23
24       libcurl  uses  a user name (and supplied or prompted password) supplied
25       with CURLOPT_USERPWD(3) or CURLOPT_USERNAME(3) in preference to any  of
26       the options controlled by this parameter.
27
28       Only  machine name, user name and password are taken into account (init
29       macros and similar things are not supported).
30
31       libcurl does not verify that the file has the  correct  properties  set
32       (as  the  standard Unix ftp client does). It should only be readable by
33       user.
34
35       level is a long that should be set to one of the values  described  be‐
36       low.
37
38       CURL_NETRC_IGNORED (0)
39              The library will ignore the .netrc file. This is the default.
40
41       CURL_NETRC_OPTIONAL (1)
42              The  use  of the .netrc file is optional, and information in the
43              URL is to be preferred.  The file will be scanned for  the  host
44              and  user name (to find the password only) or for the host only,
45              to find the first user name and  password  after  that  machine,
46              which ever information is not specified.
47
48       CURL_NETRC_REQUIRED (2)
49              The  use  of the .netrc file is required, and any credential in‐
50              formation present in the URL  is  ignored.   The  file  will  be
51              scanned  for  the host and user name (to find the password only)
52              or for the host only, to find the first user name  and  password
53              after that machine, which ever information is not specified.
54

FILE FORMAT

56       The .netrc file format is simple: you specify lines with a machine name
57       and follow the login and password that are  associated  with  that  ma‐
58       chine.
59
60       Each  field is provided as a sequence of letters that ends with a space
61       or newline. Starting in 7.84.0, libcurl also supports  quoted  strings.
62       They  start  and end with double quotes and support the escaped special
63       letters \ \r, and \t. Quoted strings are the only way a space character
64       can be used in a user namd or password.
65
66
67       machine <name>
68              Provides  credentials  for  a host called name. libcurl searches
69              the .netrc file for a machine token that matches the  host  name
70              specified  in  the URL. Once a match is made, the subsequent to‐
71              kens are processed, stopping when the end of file is reached  or
72              another "machine" is encountered.
73
74       default
75              This  is  the same as "machine" name except that default matches
76              any name. There can be only one default token, and  it  must  be
77              after  all  machine tokens. To provide a default anonymous login
78              for hosts that are not otherwise matched, add a line similar  to
79              this in the end:
80
81               default login anonymous password user@domain
82
83       login <name>
84              The user name string for the remote machine.
85
86       password <secret>
87              Supply  a  password.  If this token is present, curl will supply
88              the specified string if the remote server requires a password as
89              part  of  the login process.  Note that if this token is present
90              in the .netrc file you really should make sure the file  is  not
91              readable by anyone besides the user.
92
93       macdef <name>
94              Define a macro. This feature is not supported by libcurl. In or‐
95              der for the rest of the .netrc to still work fine, libcurl  will
96              properly skip every definition done with "macdef" that it finds.
97

DEFAULT

99       CURL_NETRC_IGNORED
100

PROTOCOLS

102       Most
103

EXAMPLE

105       CURL *curl = curl_easy_init();
106       if(curl) {
107         CURLcode ret;
108         curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/");
109         curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL);
110         ret = curl_easy_perform(curl);
111       }
112

AVAILABILITY

114       Always
115

RETURN VALUE

117       Returns CURLE_OK
118