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