curl / libcurl / API / curl_easy_setopt / CURLOPT_USERNAME

CURLOPT_USERNAME explained

Name

CURLOPT_USERNAME - username to use in authentication

Synopsis

#include <curl/curl.h>
 
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERNAME,
                          char *username);

Description

Pass a char pointer as parameter, which should be pointing to the null-terminated username to use for the transfer.

CURLOPT_USERNAME sets the username to be used in protocol authentication. You should not use this option together with the (older) CURLOPT_USERPWD option.

When using Kerberos V5 authentication with a Windows based server, you should include the ___domain name in order for the server to successfully obtain a Kerberos Ticket. If you do not then the initial part of the authentication handshake may fail.

When using NTLM, the username can be specified simply as the username without the ___domain name should the server be part of a single ___domain and forest.

To include the ___domain name use either Down-Level Logon Name or UPN (User Principal Name) formats. For example, EXAMPLEuser and user@example.com respectively.

Some HTTP servers (on Windows) support inclusion of the ___domain for Basic authentication as well.

To specify the password and login options, along with the username, use the CURLOPT_PASSWORD and CURLOPT_LOGIN_OPTIONS options.

The application does not have to keep the string around after setting this option.

Default

blank

Protocols

This functionality affects all supported protocols

Example

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode res;
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
 
    curl_easy_setopt(curl, CURLOPT_USERNAME, "clark");
 
    res = curl_easy_perform(curl);
 
    curl_easy_cleanup(curl);
  }
}

Availability

Added in curl 7.19.1

Return value

curl_easy_setopt returns a CURLcode indicating success or error.

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