xref: /curl/docs/libcurl/opts/CURLOPT_USERNAME.md (revision e3fe0200) 
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_USERNAME
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_HTTPAUTH (3)
9  - CURLOPT_PASSWORD (3)
10  - CURLOPT_PROXYAUTH (3)
11  - CURLOPT_USERPWD (3)
12Protocol:
13  - All
14---
15
16# NAME
17
18CURLOPT_USERNAME - username to use in authentication
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24
25CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERNAME,
26                          char *username);
27~~~
28
29# DESCRIPTION
30
31Pass a char pointer as parameter, which should be pointing to the
32null-terminated username to use for the transfer.
33
34CURLOPT_USERNAME(3) sets the username to be used in protocol
35authentication. You should not use this option together with the (older)
36CURLOPT_USERPWD(3) option.
37
38When using Kerberos V5 authentication with a Windows based server, you should
39include the domain name in order for the server to successfully obtain a
40Kerberos Ticket. If you do not then the initial part of the authentication
41handshake may fail.
42
43When using NTLM, the username can be specified simply as the username without
44the domain name should the server be part of a single domain and forest.
45
46To include the domain name use either Down-Level Logon Name or UPN (User
47Principal Name) formats. For example, **EXAMPLE\user** and
48**user@example.com** respectively.
49
50Some HTTP servers (on Windows) support inclusion of the domain for Basic
51authentication as well.
52
53To specify the password and login options, along with the username, use the
54CURLOPT_PASSWORD(3) and CURLOPT_LOGIN_OPTIONS(3) options.
55
56The application does not have to keep the string around after setting this
57option.
58
59# DEFAULT
60
61blank
62
63# EXAMPLE
64
65~~~c
66int main(void)
67{
68  CURL *curl = curl_easy_init();
69  if(curl) {
70    CURLcode res;
71    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
72
73    curl_easy_setopt(curl, CURLOPT_USERNAME, "clark");
74
75    res = curl_easy_perform(curl);
76
77    curl_easy_cleanup(curl);
78  }
79}
80~~~
81
82# AVAILABILITY
83
84Added in 7.19.1
85
86# RETURN VALUE
87
88Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
89CURLE_OUT_OF_MEMORY if there was insufficient heap space.
90