Artifactspublic-v0

curl

master
ply4 git calls444 ms289 KiB2 cachedprotocol v2
159 lines5.0 KiBRaw

NAME

CURLOPT_NETRC - enable use of .netrc

SYNOPSIS

c
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level);

DESCRIPTION

This parameter controls the preference level of libcurl between using usernames and passwords from your ~/.netrc file, relative to usernames and passwords in the URL supplied with CURLOPT_URL(3). If the NETRC environment variable is set, that filename is used as the netrc file. (Added in 8.16.0)

On Windows, libcurl primarily checks for .netrc in %HOME%. If %HOME% is not set on Windows, libcurl falls back to %USERPROFILE%. If the file does not exist, it falls back to check if there is instead a file named _netrc - using an underscore instead of period.

You can also tell libcurl a different filename to use with CURLOPT_NETRC_FILE(3).

libcurl uses a username (and supplied or prompted password) supplied with CURLOPT_USERPWD(3) or CURLOPT_USERNAME(3) in preference to any of the options controlled by this parameter.

Only machine name, username and password are taken into account (init macros and similar things are not supported).

The netrc file provides credentials for a hostname independent of which protocol and port number that are used.

When providing a username in the URL and a .netrc file, libcurl looks for and uses the password for that specific user for the given host if such an entry appears in the file before a "generic" machine entry without login specified.

libcurl does not verify that the file has the correct properties set (as the standard Unix ftp client does). It should only be readable by user.

level is a long that should be set to one of the values described below.

CURL_NETRC_IGNORED (0)

libcurl ignores the .netrc file. This is the default.

CURL_NETRC_OPTIONAL (1)

The use of the .netrc file is optional, and information in the URL is to be preferred. The file is scanned for the host and username (to find the password only) or for the host only, to find the first username and password after that machine, which ever information is not specified.

CURL_NETRC_REQUIRED (2)

The use of the .netrc file is required, and any credential information present in the URL is ignored. The file is scanned for the host and username (to find the password only) or for the host only, to find the first username and password after that machine, which ever information is not specified.

FILE FORMAT

The .netrc file format is simple: you specify lines with a machine name and follow the login and password that are associated with that machine.

Each field is provided as a sequence of letters that ends with a space or newline. Starting in 7.84.0, libcurl also supports quoted strings. They start and end with double quotes and support the escaped special letters ", n, r, and t. Quoted strings are the only way a space character can be used in a username or password.

machine <name>

Provides credentials for a host called name. libcurl searches the .netrc file for a machine token that matches the hostname specified in the URL. Once a match is made, the subsequent tokens are processed, stopping when the end of file is reached or another "machine" is encountered.

default

This is the same as machine name except that default matches any name. There can be only one default token, and it must be after all machine tokens. To provide a default anonymous login for hosts that are not otherwise matched, add a line similar to this in the end:

default login anonymous password user@domain

login <name>

The username string for the remote machine.

password <secret>

Supply a password. If this token is present, curl supplies the specified string if the remote server requires a password as part of the login process. Note that if this token is present in the .netrc file you really should make sure the file is not readable by anyone besides the user.

macdef <name>

Define a macro. This feature is not supported by libcurl. In order for the rest of the .netrc to still work fine, libcurl properly skips every definition done with "macdef" that it finds.

DEFAULT

CURL_NETRC_IGNORED

%PROTOCOLS%

EXAMPLE

c
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/");
    curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL);
    result = curl_easy_perform(curl);
  }
}

HISTORY

CURL_NETRC_* enums became long types in 8.13.0, prior to this version a long cast was necessary when passed to curl_easy_setopt(3).

%AVAILABILITY%

RETURN VALUE

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).

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---
16# NAME
18CURLOPT_NETRC - enable use of .netrc
20# SYNOPSIS
22~~~c
23#include <curl/curl.h>
25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_NETRC, long level);
26~~~
28# DESCRIPTION
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). If the `NETRC` environment
33variable is set, that filename is used as the netrc file. (Added in 8.16.0)
35On Windows, libcurl primarily checks for *.netrc* in *%HOME%*. If *%HOME%* is
36not set on Windows, libcurl falls back to *%USERPROFILE%*. If the file does
37not exist, it falls back to check if there is instead a file named *_netrc* -
38using an underscore instead of period.
40You can also tell libcurl a different filename to use with
41CURLOPT_NETRC_FILE(3).
43libcurl uses a username (and supplied or prompted password) supplied with
44CURLOPT_USERPWD(3) or CURLOPT_USERNAME(3) in preference to any of
45the options controlled by this parameter.
47Only machine name, username and password are taken into account (init macros
48and similar things are not supported).
50The netrc file provides credentials for a hostname independent of which
51protocol and port number that are used.
53When providing a username in the URL and a *.netrc* file, libcurl looks for
54and uses the password for that specific user for the given host if such an
55entry appears in the file before a "generic" `machine` entry without `login`
56specified.
58libcurl does not verify that the file has the correct properties set (as the
59standard Unix ftp client does). It should only be readable by user.
61*level* is a long that should be set to one of the values described below.
63## CURL_NETRC_IGNORED (0)
65libcurl ignores the *.netrc* file. This is the default.
67## CURL_NETRC_OPTIONAL (1)
69The use of the *.netrc* file is optional, and information in the URL is to
70be preferred. The file is scanned for the host and username (to find the
71password only) or for the host only, to find the first username and password
72after that *machine*, which ever information is not specified.
74## CURL_NETRC_REQUIRED (2)
76The use of the *.netrc* file is required, and any credential information
77present in the URL is ignored. The file is scanned for the host and username
78(to find the password only) or for the host only, to find the first username
79and password after that *machine*, which ever information is not
80specified.
82# FILE FORMAT
84The **.netrc** file format is simple: you specify lines with a machine name
85and follow the login and password that are associated with that machine.
87Each field is provided as a sequence of letters that ends with a space or
88newline. Starting in 7.84.0, libcurl also supports quoted strings. They start
89and end with double quotes and support the escaped special letters ", n,
90r, and t. Quoted strings are the only way a space character can be used in
91a username or password.
93## machine \<name\>
95Provides credentials for a host called **name**. libcurl searches the .netrc
96file for a machine token that matches the hostname specified in the URL. Once
97a match is made, the subsequent tokens are processed, stopping when the end of
98file is reached or another "machine" is encountered.
100## default
102This is the same as machine name except that default matches any name. There
103can be only one default token, and it must be after all machine tokens. To
104provide a default anonymous login for hosts that are not otherwise matched,
105add a line similar to this in the end:
107 default login anonymous password user@domain
109## login \<name\>
111The username string for the remote machine.
113## password \<secret\>
115Supply a password. If this token is present, curl supplies the specified
116string if the remote server requires a password as part of the login process.
117Note that if this token is present in the .netrc file you really should make
118sure the file is not readable by anyone besides the user.
120## macdef \<name\>
122Define a macro. This feature is not supported by libcurl. In order for the
123rest of the .netrc to still work fine, libcurl properly skips every definition
124done with "macdef" that it finds.
126# DEFAULT
128CURL_NETRC_IGNORED
130# %PROTOCOLS%
132# EXAMPLE
134~~~c
135int main(void)
137 CURL *curl = curl_easy_init();
138 if(curl) {
139 CURLcode result;
140 curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/");
141 curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL);
142 result = curl_easy_perform(curl);
143 }
145~~~
147# HISTORY
149**CURL_NETRC_*** enums became `long` types in 8.13.0, prior to this version
150a `long` cast was necessary when passed to curl_easy_setopt(3).
152# %AVAILABILITY%
154# RETURN VALUE
156curl_easy_setopt(3) returns a CURLcode indicating success or error.
158CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
159libcurl-errors(3).
Diagnostics4 git calls · 444 ms
CallStatusSizeTime0444 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.3 KiB439 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=439
git.response.bytes=2373
git.response.cache=MISS
git.response.duration_ms=439
git.fetch.wants=1e3dbb1dde361d840a8ccbd0e8356902e351d345
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2373
git.pkt.payload.max=2352
git.sideband.band1.bytes=2351
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e31276a8453e6e
Request
cb317f67…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format