1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_NETRC
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_NETRC_FILE (3)
9  - CURLOPT_USERNAME (3)
10  - CURLOPT_USERPWD (3)
11---
12
13# NAME
14
15CURLOPT_NETRC - enable use of .netrc
16
17# SYNOPSIS
18
19~~~c
20#include <curl/curl.h>
21
22CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level);
23~~~
24
25# DESCRIPTION
26
27This parameter controls the preference *level* of libcurl between using
28user names and passwords from your *~/.netrc* file, relative to user names
29and passwords in the URL supplied with CURLOPT_URL(3).
30
31On Windows, libcurl uses the file as *%HOME%/_netrc*. If *%HOME%* is
32not set on Windows, libcurl falls back to *%USERPROFILE%*.
33
34You can also tell libcurl a different filename to use with
35CURLOPT_NETRC_FILE(3).
36
37libcurl uses a user name (and supplied or prompted password) supplied with
38CURLOPT_USERPWD(3) or CURLOPT_USERNAME(3) in preference to any of
39the options controlled by this parameter.
40
41Only machine name, user name and password are taken into account (init macros
42and similar things are not supported).
43
44libcurl does not verify that the file has the correct properties set (as the
45standard Unix ftp client does). It should only be readable by user.
46
47*level* is a long that should be set to one of the values described below.
48
49## CURL_NETRC_IGNORED (0)
50
51libcurl ignores the *.netrc* file. This is the default.
52
53## CURL_NETRC_OPTIONAL (1)
54
55The use of the *.netrc* file is optional, and information in the URL is to
56be preferred. The file is scanned for the host and user name (to find the
57password only) or for the host only, to find the first user name and password
58after that *machine*, which ever information is not specified.
59
60## CURL_NETRC_REQUIRED (2)
61
62The use of the *.netrc* file is required, and any credential information
63present in the URL is ignored. The file is scanned for the host and user name
64(to find the password only) or for the host only, to find the first user name
65and password after that *machine*, which ever information is not
66specified.
67
68# FILE FORMAT
69
70The **.netrc** file format is simple: you specify lines with a machine name
71and follow the login and password that are associated with that machine.
72
73Each field is provided as a sequence of letters that ends with a space or
74newline. Starting in 7.84.0, libcurl also supports quoted strings. They start
75and end with double quotes and support the escaped special letters ", n,
76r, and t. Quoted strings are the only way a space character can be used in
77a user name or password.
78
79## machine <name>
80
81Provides credentials for a host called **name**. libcurl searches the .netrc
82file for a machine token that matches the hostname specified in the URL. Once
83a match is made, the subsequent tokens are processed, stopping when the end of
84file is reached or another "machine" is encountered.
85
86## default
87
88This is the same as "machine" name except that default matches any name. There
89can be only one default token, and it must be after all machine tokens. To
90provide a default anonymous login for hosts that are not otherwise matched,
91add a line similar to this in the end:
92
93 default login anonymous password user@domain
94
95## login <name>
96
97The user name string for the remote machine.
98
99## password <secret>
100
101Supply a password. If this token is present, curl supplies the specified
102string if the remote server requires a password as part of the login process.
103Note that if this token is present in the .netrc file you really should make
104sure the file is not readable by anyone besides the user.
105
106## macdef <name>
107
108Define a macro. This feature is not supported by libcurl. In order for the
109rest of the .netrc to still work fine, libcurl properly skips every definition
110done with "macdef" that it finds.
111
112# DEFAULT
113
114CURL_NETRC_IGNORED
115
116# PROTOCOLS
117
118Most
119
120# EXAMPLE
121
122~~~c
123int main(void)
124{
125  CURL *curl = curl_easy_init();
126  if(curl) {
127    CURLcode ret;
128    curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/");
129    curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL);
130    ret = curl_easy_perform(curl);
131  }
132}
133~~~
134
135# AVAILABILITY
136
137Always
138
139# RETURN VALUE
140
141Returns CURLE_OK
142