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