Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
CURLOPT_NETRC(3)	   Library Functions Manual	      CURLOPT_NETRC(3)

NAME
       CURLOPT_NETRC - enable use of .netrc

SYNOPSIS
       #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).

       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  CUR-
       LOPT_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).

       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  be-
       low.

       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 in-
	      formation	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  ma-
       chine.

       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 charac-
       ter 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  to-
	      kens  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 or-
	      der for the rest of the .netrc to	still work fine, libcurl prop-
	      erly skips every definition done with "macdef" that it finds.

DEFAULT
       CURL_NETRC_IGNORED

PROTOCOLS
       This functionality affects all supported	protocols

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

AVAILABILITY
       Added in	curl 7.1

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).

SEE ALSO
       CURLOPT_NETRC_FILE(3), CURLOPT_USERNAME(3), CURLOPT_USERPWD(3)

libcurl				  2025-06-03		      CURLOPT_NETRC(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=CURLOPT_NETRC&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help