quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

CURLOPT_NETRC.md (4590B)

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