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