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