xref: /aosp_15_r20/external/curl/docs/FAQ (revision 6236dae45794135f37c4eb022389c904c8b0090d)
1*6236dae4SAndroid Build Coastguard Worker                                  _   _ ____  _
2*6236dae4SAndroid Build Coastguard Worker                              ___| | | |  _ \| |
3*6236dae4SAndroid Build Coastguard Worker                             / __| | | | |_) | |
4*6236dae4SAndroid Build Coastguard Worker                            | (__| |_| |  _ <| |___
5*6236dae4SAndroid Build Coastguard Worker                             \___|\___/|_| \_\_____|
6*6236dae4SAndroid Build Coastguard Worker
7*6236dae4SAndroid Build Coastguard WorkerFAQ
8*6236dae4SAndroid Build Coastguard Worker
9*6236dae4SAndroid Build Coastguard Worker 1. Philosophy
10*6236dae4SAndroid Build Coastguard Worker  1.1 What is cURL?
11*6236dae4SAndroid Build Coastguard Worker  1.2 What is libcurl?
12*6236dae4SAndroid Build Coastguard Worker  1.3 What is curl not?
13*6236dae4SAndroid Build Coastguard Worker  1.4 When will you make curl do XXXX ?
14*6236dae4SAndroid Build Coastguard Worker  1.5 Who makes curl?
15*6236dae4SAndroid Build Coastguard Worker  1.6 What do you get for making curl?
16*6236dae4SAndroid Build Coastguard Worker  1.7 What about CURL from curl.com?
17*6236dae4SAndroid Build Coastguard Worker  1.8 I have a problem, who do I mail?
18*6236dae4SAndroid Build Coastguard Worker  1.9 Where do I buy commercial support for curl?
19*6236dae4SAndroid Build Coastguard Worker  1.10 How many are using curl?
20*6236dae4SAndroid Build Coastguard Worker  1.11 Why do you not update ca-bundle.crt
21*6236dae4SAndroid Build Coastguard Worker  1.12 I have a problem, who can I chat with?
22*6236dae4SAndroid Build Coastguard Worker  1.13 curl's ECCN number?
23*6236dae4SAndroid Build Coastguard Worker  1.14 How do I submit my patch?
24*6236dae4SAndroid Build Coastguard Worker  1.15 How do I port libcurl to my OS?
25*6236dae4SAndroid Build Coastguard Worker
26*6236dae4SAndroid Build Coastguard Worker 2. Install Related Problems
27*6236dae4SAndroid Build Coastguard Worker  2.1 configure fails when using static libraries
28*6236dae4SAndroid Build Coastguard Worker  2.2 Does curl work/build with other SSL libraries?
29*6236dae4SAndroid Build Coastguard Worker  2.3 How do I upgrade curl.exe in Windows?
30*6236dae4SAndroid Build Coastguard Worker  2.4 Does curl support SOCKS (RFC 1928) ?
31*6236dae4SAndroid Build Coastguard Worker
32*6236dae4SAndroid Build Coastguard Worker 3. Usage Problems
33*6236dae4SAndroid Build Coastguard Worker  3.1 curl: (1) SSL is disabled, https: not supported
34*6236dae4SAndroid Build Coastguard Worker  3.2 How do I tell curl to resume a transfer?
35*6236dae4SAndroid Build Coastguard Worker  3.3 Why does my posting using -F not work?
36*6236dae4SAndroid Build Coastguard Worker  3.4 How do I tell curl to run custom FTP commands?
37*6236dae4SAndroid Build Coastguard Worker  3.5 How can I disable the Accept: */* header?
38*6236dae4SAndroid Build Coastguard Worker  3.6 Does curl support ASP, XML, XHTML or HTML version Y?
39*6236dae4SAndroid Build Coastguard Worker  3.7 Can I use curl to delete/rename a file through FTP?
40*6236dae4SAndroid Build Coastguard Worker  3.8 How do I tell curl to follow HTTP redirects?
41*6236dae4SAndroid Build Coastguard Worker  3.9 How do I use curl in my favorite programming language?
42*6236dae4SAndroid Build Coastguard Worker  3.10 What about SOAP, WebDAV, XML-RPC or similar protocols over HTTP?
43*6236dae4SAndroid Build Coastguard Worker  3.11 How do I POST with a different Content-Type?
44*6236dae4SAndroid Build Coastguard Worker  3.12 Why do FTP-specific features over HTTP proxy fail?
45*6236dae4SAndroid Build Coastguard Worker  3.13 Why do my single/double quotes fail?
46*6236dae4SAndroid Build Coastguard Worker  3.14 Does curl support JavaScript or PAC (automated proxy config)?
47*6236dae4SAndroid Build Coastguard Worker  3.15 Can I do recursive fetches with curl?
48*6236dae4SAndroid Build Coastguard Worker  3.16 What certificates do I need when I use SSL?
49*6236dae4SAndroid Build Coastguard Worker  3.17 How do I list the root directory of an FTP server?
50*6236dae4SAndroid Build Coastguard Worker  3.18 Can I use curl to send a POST/PUT and not wait for a response?
51*6236dae4SAndroid Build Coastguard Worker  3.19 How do I get HTTP from a host using a specific IP address?
52*6236dae4SAndroid Build Coastguard Worker  3.20 How to SFTP from my user's home directory?
53*6236dae4SAndroid Build Coastguard Worker  3.21 Protocol xxx not supported or disabled in libcurl
54*6236dae4SAndroid Build Coastguard Worker  3.22 curl -X gives me HTTP problems
55*6236dae4SAndroid Build Coastguard Worker
56*6236dae4SAndroid Build Coastguard Worker 4. Running Problems
57*6236dae4SAndroid Build Coastguard Worker  4.2 Why do I get problems when I use & or % in the URL?
58*6236dae4SAndroid Build Coastguard Worker  4.3 How can I use {, }, [ or ] to specify multiple URLs?
59*6236dae4SAndroid Build Coastguard Worker  4.4 Why do I get downloaded data even though the webpage does not exist?
60*6236dae4SAndroid Build Coastguard Worker  4.5 Why do I get return code XXX from an HTTP server?
61*6236dae4SAndroid Build Coastguard Worker   4.5.1 "400 Bad Request"
62*6236dae4SAndroid Build Coastguard Worker   4.5.2 "401 Unauthorized"
63*6236dae4SAndroid Build Coastguard Worker   4.5.3 "403 Forbidden"
64*6236dae4SAndroid Build Coastguard Worker   4.5.4 "404 Not Found"
65*6236dae4SAndroid Build Coastguard Worker   4.5.5 "405 Method Not Allowed"
66*6236dae4SAndroid Build Coastguard Worker   4.5.6 "301 Moved Permanently"
67*6236dae4SAndroid Build Coastguard Worker  4.6 Can you tell me what error code 142 means?
68*6236dae4SAndroid Build Coastguard Worker  4.7 How do I keep usernames and passwords secret in curl command lines?
69*6236dae4SAndroid Build Coastguard Worker  4.8 I found a bug
70*6236dae4SAndroid Build Coastguard Worker  4.9 curl cannot authenticate to a server that requires NTLM?
71*6236dae4SAndroid Build Coastguard Worker  4.10 My HTTP request using HEAD, PUT or DELETE does not work
72*6236dae4SAndroid Build Coastguard Worker  4.11 Why do my HTTP range requests return the full document?
73*6236dae4SAndroid Build Coastguard Worker  4.12 Why do I get "certificate verify failed" ?
74*6236dae4SAndroid Build Coastguard Worker  4.13 Why is curl -R on Windows one hour off?
75*6236dae4SAndroid Build Coastguard Worker  4.14 Redirects work in browser but not with curl
76*6236dae4SAndroid Build Coastguard Worker  4.15 FTPS does not work
77*6236dae4SAndroid Build Coastguard Worker  4.16 My HTTP POST or PUT requests are slow
78*6236dae4SAndroid Build Coastguard Worker  4.17 Non-functional connect timeouts on Windows
79*6236dae4SAndroid Build Coastguard Worker  4.18 file:// URLs containing drive letters (Windows, NetWare)
80*6236dae4SAndroid Build Coastguard Worker  4.19 Why does not curl return an error when the network cable is unplugged?
81*6236dae4SAndroid Build Coastguard Worker  4.20 curl does not return error for HTTP non-200 responses
82*6236dae4SAndroid Build Coastguard Worker
83*6236dae4SAndroid Build Coastguard Worker 5. libcurl Issues
84*6236dae4SAndroid Build Coastguard Worker  5.1 Is libcurl thread-safe?
85*6236dae4SAndroid Build Coastguard Worker  5.2 How can I receive all data into a large memory chunk?
86*6236dae4SAndroid Build Coastguard Worker  5.3 How do I fetch multiple files with libcurl?
87*6236dae4SAndroid Build Coastguard Worker  5.4 Does libcurl do Winsock initialization on Win32 systems?
88*6236dae4SAndroid Build Coastguard Worker  5.5 Does CURLOPT_WRITEDATA and CURLOPT_READDATA work on Win32 ?
89*6236dae4SAndroid Build Coastguard Worker  5.6 What about Keep-Alive or persistent connections?
90*6236dae4SAndroid Build Coastguard Worker  5.7 Link errors when building libcurl on Windows
91*6236dae4SAndroid Build Coastguard Worker  5.8 libcurl.so.X: open failed: No such file or directory
92*6236dae4SAndroid Build Coastguard Worker  5.9 How does libcurl resolve hostnames?
93*6236dae4SAndroid Build Coastguard Worker  5.10 How do I prevent libcurl from writing the response to stdout?
94*6236dae4SAndroid Build Coastguard Worker  5.11 How do I make libcurl not receive the whole HTTP response?
95*6236dae4SAndroid Build Coastguard Worker  5.12 Can I make libcurl fake or hide my real IP address?
96*6236dae4SAndroid Build Coastguard Worker  5.13 How do I stop an ongoing transfer?
97*6236dae4SAndroid Build Coastguard Worker  5.14 Using C++ non-static functions for callbacks?
98*6236dae4SAndroid Build Coastguard Worker  5.15 How do I get an FTP directory listing?
99*6236dae4SAndroid Build Coastguard Worker  5.16 I want a different time-out
100*6236dae4SAndroid Build Coastguard Worker  5.17 Can I write a server with libcurl?
101*6236dae4SAndroid Build Coastguard Worker  5.18 Does libcurl use threads?
102*6236dae4SAndroid Build Coastguard Worker
103*6236dae4SAndroid Build Coastguard Worker 6. License Issues
104*6236dae4SAndroid Build Coastguard Worker  6.1 I have a GPL program, can I use the libcurl library?
105*6236dae4SAndroid Build Coastguard Worker  6.2 I have a closed-source program, can I use the libcurl library?
106*6236dae4SAndroid Build Coastguard Worker  6.3 I have a BSD licensed program, can I use the libcurl library?
107*6236dae4SAndroid Build Coastguard Worker  6.4 I have a program that uses LGPL libraries, can I use libcurl?
108*6236dae4SAndroid Build Coastguard Worker  6.5 Can I modify curl/libcurl for my program and keep the changes secret?
109*6236dae4SAndroid Build Coastguard Worker  6.6 Can you please change the curl/libcurl license to XXXX?
110*6236dae4SAndroid Build Coastguard Worker  6.7 What are my obligations when using libcurl in my commercial apps?
111*6236dae4SAndroid Build Coastguard Worker
112*6236dae4SAndroid Build Coastguard Worker 7. PHP/CURL Issues
113*6236dae4SAndroid Build Coastguard Worker  7.1 What is PHP/CURL?
114*6236dae4SAndroid Build Coastguard Worker  7.2 Who wrote PHP/CURL?
115*6236dae4SAndroid Build Coastguard Worker  7.3 Can I perform multiple requests using the same handle?
116*6236dae4SAndroid Build Coastguard Worker  7.4 Does PHP/CURL have dependencies?
117*6236dae4SAndroid Build Coastguard Worker
118*6236dae4SAndroid Build Coastguard Worker 8. Development
119*6236dae4SAndroid Build Coastguard Worker  8.1 Why does curl use C89?
120*6236dae4SAndroid Build Coastguard Worker  8.2 Will curl be rewritten?
121*6236dae4SAndroid Build Coastguard Worker
122*6236dae4SAndroid Build Coastguard Worker==============================================================================
123*6236dae4SAndroid Build Coastguard Worker
124*6236dae4SAndroid Build Coastguard Worker1. Philosophy
125*6236dae4SAndroid Build Coastguard Worker
126*6236dae4SAndroid Build Coastguard Worker  1.1 What is cURL?
127*6236dae4SAndroid Build Coastguard Worker
128*6236dae4SAndroid Build Coastguard Worker  cURL is the name of the project. The name is a play on 'Client for URLs',
129*6236dae4SAndroid Build Coastguard Worker  originally with URL spelled in uppercase to make it obvious it deals with
130*6236dae4SAndroid Build Coastguard Worker  URLs. The fact it can also be read as 'see URL' also helped, it works as
131*6236dae4SAndroid Build Coastguard Worker  an abbreviation for "Client URL Request Library" or why not the recursive
132*6236dae4SAndroid Build Coastguard Worker  version: "curl URL Request Library".
133*6236dae4SAndroid Build Coastguard Worker
134*6236dae4SAndroid Build Coastguard Worker  The cURL project produces two products:
135*6236dae4SAndroid Build Coastguard Worker
136*6236dae4SAndroid Build Coastguard Worker  libcurl
137*6236dae4SAndroid Build Coastguard Worker
138*6236dae4SAndroid Build Coastguard Worker    A client-side URL transfer library, supporting DICT, FILE, FTP, FTPS,
139*6236dae4SAndroid Build Coastguard Worker    GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S,
140*6236dae4SAndroid Build Coastguard Worker    RTMP, RTMPS, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS
141*6236dae4SAndroid Build Coastguard Worker    and WSS.
142*6236dae4SAndroid Build Coastguard Worker
143*6236dae4SAndroid Build Coastguard Worker    libcurl supports HTTPS certificates, HTTP POST, HTTP PUT, FTP uploading,
144*6236dae4SAndroid Build Coastguard Worker    Kerberos, SPNEGO, HTTP form based upload, proxies, cookies, user+password
145*6236dae4SAndroid Build Coastguard Worker    authentication, file transfer resume, http proxy tunneling and more.
146*6236dae4SAndroid Build Coastguard Worker
147*6236dae4SAndroid Build Coastguard Worker    libcurl is highly portable, it builds and works identically on numerous
148*6236dae4SAndroid Build Coastguard Worker    platforms, including Solaris, NetBSD, FreeBSD, OpenBSD, Darwin, HP-UX,
149*6236dae4SAndroid Build Coastguard Worker    IRIX, AIX, Tru64, Linux, UnixWare, HURD, Windows, Amiga, OS/2, macOS,
150*6236dae4SAndroid Build Coastguard Worker    Ultrix, QNX, OpenVMS, RISC OS, Novell NetWare, DOS, Symbian, OSF, Android,
151*6236dae4SAndroid Build Coastguard Worker    Minix, IBM TPF and more...
152*6236dae4SAndroid Build Coastguard Worker
153*6236dae4SAndroid Build Coastguard Worker    libcurl is free, thread-safe, IPv6 compatible, feature rich, well
154*6236dae4SAndroid Build Coastguard Worker    supported and fast.
155*6236dae4SAndroid Build Coastguard Worker
156*6236dae4SAndroid Build Coastguard Worker  curl
157*6236dae4SAndroid Build Coastguard Worker
158*6236dae4SAndroid Build Coastguard Worker    A command line tool for getting or sending data using URL syntax.
159*6236dae4SAndroid Build Coastguard Worker
160*6236dae4SAndroid Build Coastguard Worker    Since curl uses libcurl, curl supports the same wide range of common
161*6236dae4SAndroid Build Coastguard Worker    Internet protocols that libcurl does.
162*6236dae4SAndroid Build Coastguard Worker
163*6236dae4SAndroid Build Coastguard Worker  We pronounce curl with an initial k sound. It rhymes with words like girl
164*6236dae4SAndroid Build Coastguard Worker  and earl. This is a short WAV file to help you:
165*6236dae4SAndroid Build Coastguard Worker
166*6236dae4SAndroid Build Coastguard Worker     https://media.merriam-webster.com/soundc11/c/curl0001.wav
167*6236dae4SAndroid Build Coastguard Worker
168*6236dae4SAndroid Build Coastguard Worker  There are numerous sub-projects and related projects that also use the word
169*6236dae4SAndroid Build Coastguard Worker  curl in the project names in various combinations, but you should take
170*6236dae4SAndroid Build Coastguard Worker  notice that this FAQ is directed at the command-line tool named curl (and
171*6236dae4SAndroid Build Coastguard Worker  libcurl the library), and may therefore not be valid for other curl-related
172*6236dae4SAndroid Build Coastguard Worker  projects. (There is however a small section for the PHP/CURL in this FAQ.)
173*6236dae4SAndroid Build Coastguard Worker
174*6236dae4SAndroid Build Coastguard Worker  1.2 What is libcurl?
175*6236dae4SAndroid Build Coastguard Worker
176*6236dae4SAndroid Build Coastguard Worker  libcurl is a reliable and portable library for doing Internet data transfers
177*6236dae4SAndroid Build Coastguard Worker  using one or more of its supported Internet protocols.
178*6236dae4SAndroid Build Coastguard Worker
179*6236dae4SAndroid Build Coastguard Worker  You can use libcurl freely in your application, be it open source,
180*6236dae4SAndroid Build Coastguard Worker  commercial or closed-source.
181*6236dae4SAndroid Build Coastguard Worker
182*6236dae4SAndroid Build Coastguard Worker  libcurl is most probably the most portable, most powerful and most often
183*6236dae4SAndroid Build Coastguard Worker  used C-based multi-platform file transfer library on this planet - be it
184*6236dae4SAndroid Build Coastguard Worker  open source or commercial.
185*6236dae4SAndroid Build Coastguard Worker
186*6236dae4SAndroid Build Coastguard Worker  1.3 What is curl not?
187*6236dae4SAndroid Build Coastguard Worker
188*6236dae4SAndroid Build Coastguard Worker  curl is not a wget clone. That is a common misconception. Never, during
189*6236dae4SAndroid Build Coastguard Worker  curl's development, have we intended curl to replace wget or compete on its
190*6236dae4SAndroid Build Coastguard Worker  market. curl is targeted at single-shot file transfers.
191*6236dae4SAndroid Build Coastguard Worker
192*6236dae4SAndroid Build Coastguard Worker  curl is not a website mirroring program. If you want to use curl to mirror
193*6236dae4SAndroid Build Coastguard Worker  something: fine, go ahead and write a script that wraps around curl or use
194*6236dae4SAndroid Build Coastguard Worker  libcurl to make it reality.
195*6236dae4SAndroid Build Coastguard Worker
196*6236dae4SAndroid Build Coastguard Worker  curl is not an FTP site mirroring program. Sure, get and send FTP with curl
197*6236dae4SAndroid Build Coastguard Worker  but if you want systematic and sequential behavior you should write a
198*6236dae4SAndroid Build Coastguard Worker  script (or write a new program that interfaces libcurl) and do it.
199*6236dae4SAndroid Build Coastguard Worker
200*6236dae4SAndroid Build Coastguard Worker  curl is not a PHP tool, even though it works perfectly well when used from
201*6236dae4SAndroid Build Coastguard Worker  or with PHP (when using the PHP/CURL module).
202*6236dae4SAndroid Build Coastguard Worker
203*6236dae4SAndroid Build Coastguard Worker  curl is not a program for a single operating system. curl exists, compiles,
204*6236dae4SAndroid Build Coastguard Worker  builds and runs under a wide range of operating systems, including all
205*6236dae4SAndroid Build Coastguard Worker  modern Unixes (and a bunch of older ones too), Windows, Amiga, OS/2, macOS,
206*6236dae4SAndroid Build Coastguard Worker  QNX etc.
207*6236dae4SAndroid Build Coastguard Worker
208*6236dae4SAndroid Build Coastguard Worker  1.4 When will you make curl do XXXX ?
209*6236dae4SAndroid Build Coastguard Worker
210*6236dae4SAndroid Build Coastguard Worker  We love suggestions of what to change in order to make curl and libcurl
211*6236dae4SAndroid Build Coastguard Worker  better. We do however believe in a few rules when it comes to the future of
212*6236dae4SAndroid Build Coastguard Worker  curl:
213*6236dae4SAndroid Build Coastguard Worker
214*6236dae4SAndroid Build Coastguard Worker  curl -- the command line tool -- is to remain a non-graphical command line
215*6236dae4SAndroid Build Coastguard Worker  tool. If you want GUIs or fancy scripting capabilities, you should look for
216*6236dae4SAndroid Build Coastguard Worker  another tool that uses libcurl.
217*6236dae4SAndroid Build Coastguard Worker
218*6236dae4SAndroid Build Coastguard Worker  We do not add things to curl that other small and available tools already do
219*6236dae4SAndroid Build Coastguard Worker  well at the side. curl's output can be piped into another program or
220*6236dae4SAndroid Build Coastguard Worker  redirected to another file for the next program to interpret.
221*6236dae4SAndroid Build Coastguard Worker
222*6236dae4SAndroid Build Coastguard Worker  We focus on protocol related issues and improvements. If you want to do more
223*6236dae4SAndroid Build Coastguard Worker  magic with the supported protocols than curl currently does, chances are
224*6236dae4SAndroid Build Coastguard Worker  good we will agree. If you want to add more protocols, we may agree.
225*6236dae4SAndroid Build Coastguard Worker
226*6236dae4SAndroid Build Coastguard Worker  If you want someone else to do all the work while you wait for us to
227*6236dae4SAndroid Build Coastguard Worker  implement it for you, that is not a friendly attitude. We spend a
228*6236dae4SAndroid Build Coastguard Worker  considerable time already on maintaining and developing curl. In order to
229*6236dae4SAndroid Build Coastguard Worker  get more out of us, you should consider trading in some of your time and
230*6236dae4SAndroid Build Coastguard Worker  effort in return. Simply go to the GitHub repository which resides at
231*6236dae4SAndroid Build Coastguard Worker  https://github.com/curl/curl, fork the project, and create pull requests
232*6236dae4SAndroid Build Coastguard Worker  with your proposed changes.
233*6236dae4SAndroid Build Coastguard Worker
234*6236dae4SAndroid Build Coastguard Worker  If you write the code, chances are better that it will get into curl faster.
235*6236dae4SAndroid Build Coastguard Worker
236*6236dae4SAndroid Build Coastguard Worker  1.5 Who makes curl?
237*6236dae4SAndroid Build Coastguard Worker
238*6236dae4SAndroid Build Coastguard Worker  curl and libcurl are not made by any single individual. Daniel Stenberg is
239*6236dae4SAndroid Build Coastguard Worker  project leader and main developer, but other persons' submissions are
240*6236dae4SAndroid Build Coastguard Worker  important and crucial. Anyone can contribute and post their changes and
241*6236dae4SAndroid Build Coastguard Worker  improvements and have them inserted in the main sources (of course on the
242*6236dae4SAndroid Build Coastguard Worker  condition that developers agree that the fixes are good).
243*6236dae4SAndroid Build Coastguard Worker
244*6236dae4SAndroid Build Coastguard Worker  The full list of all contributors is found in the docs/THANKS file.
245*6236dae4SAndroid Build Coastguard Worker
246*6236dae4SAndroid Build Coastguard Worker  curl is developed by a community, with Daniel at the wheel.
247*6236dae4SAndroid Build Coastguard Worker
248*6236dae4SAndroid Build Coastguard Worker  1.6 What do you get for making curl?
249*6236dae4SAndroid Build Coastguard Worker
250*6236dae4SAndroid Build Coastguard Worker  Project cURL is entirely free and open. We do this voluntarily, mostly in
251*6236dae4SAndroid Build Coastguard Worker  our spare time. Companies may pay individual developers to work on curl.
252*6236dae4SAndroid Build Coastguard Worker  This is not controlled by nor supervised in any way by the curl project.
253*6236dae4SAndroid Build Coastguard Worker
254*6236dae4SAndroid Build Coastguard Worker  We get help from companies. Haxx provides website, bandwidth, mailing lists
255*6236dae4SAndroid Build Coastguard Worker  etc, GitHub hosts the primary git repository and other services like the bug
256*6236dae4SAndroid Build Coastguard Worker  tracker at https://github.com/curl/curl. Also again, some companies have
257*6236dae4SAndroid Build Coastguard Worker  sponsored certain parts of the development in the past and I hope some will
258*6236dae4SAndroid Build Coastguard Worker  continue to do so in the future.
259*6236dae4SAndroid Build Coastguard Worker
260*6236dae4SAndroid Build Coastguard Worker  If you want to support our project, consider a donation or a banner-program
261*6236dae4SAndroid Build Coastguard Worker  or even better: by helping us with coding, documenting or testing etc.
262*6236dae4SAndroid Build Coastguard Worker
263*6236dae4SAndroid Build Coastguard Worker  See also: https://curl.se/sponsors.html
264*6236dae4SAndroid Build Coastguard Worker
265*6236dae4SAndroid Build Coastguard Worker  1.7 What about CURL from curl.com?
266*6236dae4SAndroid Build Coastguard Worker
267*6236dae4SAndroid Build Coastguard Worker  During the summer of 2001, curl.com was busy advertising their client-side
268*6236dae4SAndroid Build Coastguard Worker  programming language for the web, named CURL.
269*6236dae4SAndroid Build Coastguard Worker
270*6236dae4SAndroid Build Coastguard Worker  We are in no way associated with curl.com or their CURL programming
271*6236dae4SAndroid Build Coastguard Worker  language.
272*6236dae4SAndroid Build Coastguard Worker
273*6236dae4SAndroid Build Coastguard Worker  Our project name curl has been in effective use since 1998. We were not the
274*6236dae4SAndroid Build Coastguard Worker  first computer related project to use the name "curl" and do not claim any
275*6236dae4SAndroid Build Coastguard Worker  rights to the name.
276*6236dae4SAndroid Build Coastguard Worker
277*6236dae4SAndroid Build Coastguard Worker  We recognize that we will be living in parallel with curl.com and wish them
278*6236dae4SAndroid Build Coastguard Worker  every success.
279*6236dae4SAndroid Build Coastguard Worker
280*6236dae4SAndroid Build Coastguard Worker  1.8 I have a problem, who do I mail?
281*6236dae4SAndroid Build Coastguard Worker
282*6236dae4SAndroid Build Coastguard Worker  Please do not mail any single individual unless you really need to. Keep
283*6236dae4SAndroid Build Coastguard Worker  curl-related questions on a suitable mailing list. All available mailing
284*6236dae4SAndroid Build Coastguard Worker  lists are listed in the MANUAL document and online at
285*6236dae4SAndroid Build Coastguard Worker  https://curl.se/mail/
286*6236dae4SAndroid Build Coastguard Worker
287*6236dae4SAndroid Build Coastguard Worker  Keeping curl-related questions and discussions on mailing lists allows
288*6236dae4SAndroid Build Coastguard Worker  others to join in and help, to share their ideas, to contribute their
289*6236dae4SAndroid Build Coastguard Worker  suggestions and to spread their wisdom. Keeping discussions on public mailing
290*6236dae4SAndroid Build Coastguard Worker  lists also allows for others to learn from this (both current and future
291*6236dae4SAndroid Build Coastguard Worker  users thanks to the web based archives of the mailing lists), thus saving us
292*6236dae4SAndroid Build Coastguard Worker  from having to repeat ourselves even more. Thanks for respecting this.
293*6236dae4SAndroid Build Coastguard Worker
294*6236dae4SAndroid Build Coastguard Worker  If you have found or simply suspect a security problem in curl or libcurl,
295*6236dae4SAndroid Build Coastguard Worker  submit all the details at https://hackerone.one/curl. On there we keep the
296*6236dae4SAndroid Build Coastguard Worker  issue private while we investigate, confirm it, work and validate a fix and
297*6236dae4SAndroid Build Coastguard Worker  agree on a time schedule for publication etc. That way we produce a fix in a
298*6236dae4SAndroid Build Coastguard Worker  timely manner before the flaw is announced to the world, reducing the impact
299*6236dae4SAndroid Build Coastguard Worker  the problem risks having on existing users.
300*6236dae4SAndroid Build Coastguard Worker
301*6236dae4SAndroid Build Coastguard Worker  Security issues can also be taking to the curl security team by emailing
302*6236dae4SAndroid Build Coastguard Worker  security at curl.se (closed list of receivers, mails are not disclosed).
303*6236dae4SAndroid Build Coastguard Worker
304*6236dae4SAndroid Build Coastguard Worker  1.9 Where do I buy commercial support for curl?
305*6236dae4SAndroid Build Coastguard Worker
306*6236dae4SAndroid Build Coastguard Worker  curl is fully open source. It means you can hire any skilled engineer to fix
307*6236dae4SAndroid Build Coastguard Worker  your curl-related problems.
308*6236dae4SAndroid Build Coastguard Worker
309*6236dae4SAndroid Build Coastguard Worker  We list available alternatives on the curl website:
310*6236dae4SAndroid Build Coastguard Worker  https://curl.se/support.html
311*6236dae4SAndroid Build Coastguard Worker
312*6236dae4SAndroid Build Coastguard Worker  1.10 How many are using curl?
313*6236dae4SAndroid Build Coastguard Worker
314*6236dae4SAndroid Build Coastguard Worker  It is impossible to tell.
315*6236dae4SAndroid Build Coastguard Worker
316*6236dae4SAndroid Build Coastguard Worker  We do not know how many users that knowingly have installed and use curl.
317*6236dae4SAndroid Build Coastguard Worker
318*6236dae4SAndroid Build Coastguard Worker  We do not know how many users that use curl without knowing that they are in
319*6236dae4SAndroid Build Coastguard Worker  fact using it.
320*6236dae4SAndroid Build Coastguard Worker
321*6236dae4SAndroid Build Coastguard Worker  We do not know how many users that downloaded or installed curl and then
322*6236dae4SAndroid Build Coastguard Worker  never use it.
323*6236dae4SAndroid Build Coastguard Worker
324*6236dae4SAndroid Build Coastguard Worker  In 2020, we estimate that curl runs in roughly ten billion installations
325*6236dae4SAndroid Build Coastguard Worker  world wide.
326*6236dae4SAndroid Build Coastguard Worker
327*6236dae4SAndroid Build Coastguard Worker  1.11 Why do you not update ca-bundle.crt
328*6236dae4SAndroid Build Coastguard Worker
329*6236dae4SAndroid Build Coastguard Worker  In the cURL project we have decided not to attempt to keep this file updated
330*6236dae4SAndroid Build Coastguard Worker  (or even present) since deciding what to add to a ca cert bundle is an
331*6236dae4SAndroid Build Coastguard Worker  undertaking we have not been ready to accept, and the one we can get from
332*6236dae4SAndroid Build Coastguard Worker  Mozilla is perfectly fine so there is no need to duplicate that work.
333*6236dae4SAndroid Build Coastguard Worker
334*6236dae4SAndroid Build Coastguard Worker  Today, with many services performed over HTTPS, every operating system
335*6236dae4SAndroid Build Coastguard Worker  should come with a default ca cert bundle that can be deemed somewhat
336*6236dae4SAndroid Build Coastguard Worker  trustworthy and that collection (if reasonably updated) should be deemed to
337*6236dae4SAndroid Build Coastguard Worker  be a lot better than a private curl version.
338*6236dae4SAndroid Build Coastguard Worker
339*6236dae4SAndroid Build Coastguard Worker  If you want the most recent collection of ca certs that Mozilla Firefox
340*6236dae4SAndroid Build Coastguard Worker  uses, we recommend that you extract the collection yourself from Mozilla
341*6236dae4SAndroid Build Coastguard Worker  Firefox (by running 'make ca-bundle), or by using our online service setup
342*6236dae4SAndroid Build Coastguard Worker  for this purpose: https://curl.se/docs/caextract.html
343*6236dae4SAndroid Build Coastguard Worker
344*6236dae4SAndroid Build Coastguard Worker  1.12 I have a problem who, can I chat with?
345*6236dae4SAndroid Build Coastguard Worker
346*6236dae4SAndroid Build Coastguard Worker  There is a bunch of friendly people hanging out in the #curl channel on the
347*6236dae4SAndroid Build Coastguard Worker  IRC network libera.chat. If you are polite and nice, chances are good that
348*6236dae4SAndroid Build Coastguard Worker  you can get -- or provide -- help instantly.
349*6236dae4SAndroid Build Coastguard Worker
350*6236dae4SAndroid Build Coastguard Worker  1.13 curl's ECCN number?
351*6236dae4SAndroid Build Coastguard Worker
352*6236dae4SAndroid Build Coastguard Worker  The US government restricts exports of software that contains or uses
353*6236dae4SAndroid Build Coastguard Worker  cryptography. When doing so, the Export Control Classification Number (ECCN)
354*6236dae4SAndroid Build Coastguard Worker  is used to identify the level of export control etc.
355*6236dae4SAndroid Build Coastguard Worker
356*6236dae4SAndroid Build Coastguard Worker  Apache Software Foundation gives a good explanation of ECCNs at
357*6236dae4SAndroid Build Coastguard Worker  https://www.apache.org/dev/crypto.html
358*6236dae4SAndroid Build Coastguard Worker
359*6236dae4SAndroid Build Coastguard Worker  We believe curl's number might be ECCN 5D002, another possibility is
360*6236dae4SAndroid Build Coastguard Worker  5D992. It seems necessary to write them (the authority that administers ECCN
361*6236dae4SAndroid Build Coastguard Worker  numbers), asking to confirm.
362*6236dae4SAndroid Build Coastguard Worker
363*6236dae4SAndroid Build Coastguard Worker  Comprehensible explanations of the meaning of such numbers and how to obtain
364*6236dae4SAndroid Build Coastguard Worker  them (resp.) are here
365*6236dae4SAndroid Build Coastguard Worker
366*6236dae4SAndroid Build Coastguard Worker  https://www.bis.doc.gov/licensing/exportingbasics.htm
367*6236dae4SAndroid Build Coastguard Worker  https://www.bis.doc.gov/licensing/do_i_needaneccn.html
368*6236dae4SAndroid Build Coastguard Worker
369*6236dae4SAndroid Build Coastguard Worker  An incomprehensible description of the two numbers above is here
370*6236dae4SAndroid Build Coastguard Worker  https://www.bis.doc.gov/index.php/documents/new-encryption/1653-ccl5-pt2-3
371*6236dae4SAndroid Build Coastguard Worker
372*6236dae4SAndroid Build Coastguard Worker  1.14 How do I submit my patch?
373*6236dae4SAndroid Build Coastguard Worker
374*6236dae4SAndroid Build Coastguard Worker  We strongly encourage you to submit changes and improvements directly as
375*6236dae4SAndroid Build Coastguard Worker  "pull requests" on GitHub: https://github.com/curl/curl/pulls
376*6236dae4SAndroid Build Coastguard Worker
377*6236dae4SAndroid Build Coastguard Worker  If you for any reason cannot or will not deal with GitHub, send your patch to
378*6236dae4SAndroid Build Coastguard Worker  the curl-library mailing list. We are many subscribers there and there are
379*6236dae4SAndroid Build Coastguard Worker  lots of people who can review patches, comment on them and "receive" them
380*6236dae4SAndroid Build Coastguard Worker  properly.
381*6236dae4SAndroid Build Coastguard Worker
382*6236dae4SAndroid Build Coastguard Worker  Lots of more details are found in the CONTRIBUTE.md and INTERNALS.md
383*6236dae4SAndroid Build Coastguard Worker  documents.
384*6236dae4SAndroid Build Coastguard Worker
385*6236dae4SAndroid Build Coastguard Worker  1.15 How do I port libcurl to my OS?
386*6236dae4SAndroid Build Coastguard Worker
387*6236dae4SAndroid Build Coastguard Worker  Here's a rough step-by-step:
388*6236dae4SAndroid Build Coastguard Worker
389*6236dae4SAndroid Build Coastguard Worker  1. copy a suitable lib/config-*.h file as a start to lib/config-[youros].h
390*6236dae4SAndroid Build Coastguard Worker
391*6236dae4SAndroid Build Coastguard Worker  2. edit lib/config-[youros].h to match your OS and setup
392*6236dae4SAndroid Build Coastguard Worker
393*6236dae4SAndroid Build Coastguard Worker  3. edit lib/curl_setup.h to include config-[youros].h when your OS is
394*6236dae4SAndroid Build Coastguard Worker     detected by the preprocessor, in the style others already exist
395*6236dae4SAndroid Build Coastguard Worker
396*6236dae4SAndroid Build Coastguard Worker  4. compile lib/*.c and make them into a library
397*6236dae4SAndroid Build Coastguard Worker
398*6236dae4SAndroid Build Coastguard Worker
399*6236dae4SAndroid Build Coastguard Worker2. Install Related Problems
400*6236dae4SAndroid Build Coastguard Worker
401*6236dae4SAndroid Build Coastguard Worker  2.1 configure fails when using static libraries
402*6236dae4SAndroid Build Coastguard Worker
403*6236dae4SAndroid Build Coastguard Worker  You may find that configure fails to properly detect the entire dependency
404*6236dae4SAndroid Build Coastguard Worker  chain of libraries when you provide static versions of the libraries that
405*6236dae4SAndroid Build Coastguard Worker  configure checks for.
406*6236dae4SAndroid Build Coastguard Worker
407*6236dae4SAndroid Build Coastguard Worker  The reason why static libraries is much harder to deal with is that for them
408*6236dae4SAndroid Build Coastguard Worker  we do not get any help but the script itself must know or check what more
409*6236dae4SAndroid Build Coastguard Worker  libraries that are needed (with shared libraries, that dependency "chain" is
410*6236dae4SAndroid Build Coastguard Worker  handled automatically). This is an error-prone process and one that also
411*6236dae4SAndroid Build Coastguard Worker  tends to vary over time depending on the release versions of the involved
412*6236dae4SAndroid Build Coastguard Worker  components and may also differ between operating systems.
413*6236dae4SAndroid Build Coastguard Worker
414*6236dae4SAndroid Build Coastguard Worker  For that reason, configure does few attempts to actually figure this out and
415*6236dae4SAndroid Build Coastguard Worker  you are instead encouraged to set LIBS and LDFLAGS accordingly when you
416*6236dae4SAndroid Build Coastguard Worker  invoke configure, and point out the needed libraries and set the necessary
417*6236dae4SAndroid Build Coastguard Worker  flags yourself.
418*6236dae4SAndroid Build Coastguard Worker
419*6236dae4SAndroid Build Coastguard Worker  2.2 Does curl work with other SSL libraries?
420*6236dae4SAndroid Build Coastguard Worker
421*6236dae4SAndroid Build Coastguard Worker  curl has been written to use a generic SSL function layer internally, and
422*6236dae4SAndroid Build Coastguard Worker  that SSL functionality can then be provided by one out of many different SSL
423*6236dae4SAndroid Build Coastguard Worker  backends.
424*6236dae4SAndroid Build Coastguard Worker
425*6236dae4SAndroid Build Coastguard Worker  curl can be built to use one of the following SSL alternatives: OpenSSL,
426*6236dae4SAndroid Build Coastguard Worker  LibreSSL, BoringSSL, AWS-LC, GnuTLS, wolfSSL, mbedTLS, Secure Transport
427*6236dae4SAndroid Build Coastguard Worker  (native iOS/macOS), Schannel (native Windows), BearSSL or Rustls. They all
428*6236dae4SAndroid Build Coastguard Worker  have their pros and cons, and we try to maintain a comparison of them here:
429*6236dae4SAndroid Build Coastguard Worker  https://curl.se/docs/ssl-compared.html
430*6236dae4SAndroid Build Coastguard Worker
431*6236dae4SAndroid Build Coastguard Worker  2.3 How do I upgrade curl.exe in Windows?
432*6236dae4SAndroid Build Coastguard Worker
433*6236dae4SAndroid Build Coastguard Worker  The curl tool that is shipped as an integrated component of Windows 10 and
434*6236dae4SAndroid Build Coastguard Worker  Windows 11 is managed by Microsoft. If you were to delete the file or
435*6236dae4SAndroid Build Coastguard Worker  replace it with a newer version downloaded from https://curl.se/windows,
436*6236dae4SAndroid Build Coastguard Worker  then Windows Update will cease to work on your system.
437*6236dae4SAndroid Build Coastguard Worker
438*6236dae4SAndroid Build Coastguard Worker  There is no way to independently force an upgrade of the curl.exe that is
439*6236dae4SAndroid Build Coastguard Worker  part of Windows other than through the regular Windows update process. There
440*6236dae4SAndroid Build Coastguard Worker  is also nothing the curl project itself can do about this, since this is
441*6236dae4SAndroid Build Coastguard Worker  managed and controlled entirely by Microsoft as owners of the operating
442*6236dae4SAndroid Build Coastguard Worker  system.
443*6236dae4SAndroid Build Coastguard Worker
444*6236dae4SAndroid Build Coastguard Worker  You can always download and install the latest version of curl for Windows
445*6236dae4SAndroid Build Coastguard Worker  from https://curl.se/windows into a separate location.
446*6236dae4SAndroid Build Coastguard Worker
447*6236dae4SAndroid Build Coastguard Worker  2.4 Does curl support SOCKS (RFC 1928) ?
448*6236dae4SAndroid Build Coastguard Worker
449*6236dae4SAndroid Build Coastguard Worker  Yes, SOCKS 4 and 5 are supported.
450*6236dae4SAndroid Build Coastguard Worker
451*6236dae4SAndroid Build Coastguard Worker3. Usage problems
452*6236dae4SAndroid Build Coastguard Worker
453*6236dae4SAndroid Build Coastguard Worker  3.1 curl: (1) SSL is disabled, https: not supported
454*6236dae4SAndroid Build Coastguard Worker
455*6236dae4SAndroid Build Coastguard Worker  If you get this output when trying to get anything from an HTTPS server, it
456*6236dae4SAndroid Build Coastguard Worker  means that the instance of curl/libcurl that you are using was built without
457*6236dae4SAndroid Build Coastguard Worker  support for this protocol.
458*6236dae4SAndroid Build Coastguard Worker
459*6236dae4SAndroid Build Coastguard Worker  This could have happened if the configure script that was run at build time
460*6236dae4SAndroid Build Coastguard Worker  could not find all libs and include files curl requires for SSL to work. If
461*6236dae4SAndroid Build Coastguard Worker  the configure script fails to find them, curl is simply built without SSL
462*6236dae4SAndroid Build Coastguard Worker  support.
463*6236dae4SAndroid Build Coastguard Worker
464*6236dae4SAndroid Build Coastguard Worker  To get HTTPS support into a curl that was previously built but that reports
465*6236dae4SAndroid Build Coastguard Worker  that HTTPS is not supported, you should dig through the document and logs
466*6236dae4SAndroid Build Coastguard Worker  and check out why the configure script does not find the SSL libs and/or
467*6236dae4SAndroid Build Coastguard Worker  include files.
468*6236dae4SAndroid Build Coastguard Worker
469*6236dae4SAndroid Build Coastguard Worker  Also, check out the other paragraph in this FAQ labeled "configure does not
470*6236dae4SAndroid Build Coastguard Worker  find OpenSSL even when it is installed".
471*6236dae4SAndroid Build Coastguard Worker
472*6236dae4SAndroid Build Coastguard Worker  3.2 How do I tell curl to resume a transfer?
473*6236dae4SAndroid Build Coastguard Worker
474*6236dae4SAndroid Build Coastguard Worker  curl supports resumed transfers both ways on both FTP and HTTP.
475*6236dae4SAndroid Build Coastguard Worker  Try the -C option.
476*6236dae4SAndroid Build Coastguard Worker
477*6236dae4SAndroid Build Coastguard Worker  3.3 Why does my posting using -F not work?
478*6236dae4SAndroid Build Coastguard Worker
479*6236dae4SAndroid Build Coastguard Worker  You cannot arbitrarily use -F or -d, the choice between -F or -d depends on
480*6236dae4SAndroid Build Coastguard Worker  the HTTP operation you need curl to do and what the web server that will
481*6236dae4SAndroid Build Coastguard Worker  receive your post expects.
482*6236dae4SAndroid Build Coastguard Worker
483*6236dae4SAndroid Build Coastguard Worker  If the form you are trying to submit uses the type 'multipart/form-data',
484*6236dae4SAndroid Build Coastguard Worker  then and only then you must use the -F type. In all the most common cases,
485*6236dae4SAndroid Build Coastguard Worker  you should use -d which then causes a posting with the type
486*6236dae4SAndroid Build Coastguard Worker  'application/x-www-form-urlencoded'.
487*6236dae4SAndroid Build Coastguard Worker
488*6236dae4SAndroid Build Coastguard Worker  This is described in some detail in the MANUAL and TheArtOfHttpScripting
489*6236dae4SAndroid Build Coastguard Worker  documents, and if you do not understand it the first time, read it again
490*6236dae4SAndroid Build Coastguard Worker  before you post questions about this to the mailing list. Also, try reading
491*6236dae4SAndroid Build Coastguard Worker  through the mailing list archives for old postings and questions regarding
492*6236dae4SAndroid Build Coastguard Worker  this.
493*6236dae4SAndroid Build Coastguard Worker
494*6236dae4SAndroid Build Coastguard Worker  3.4 How do I tell curl to run custom FTP commands?
495*6236dae4SAndroid Build Coastguard Worker
496*6236dae4SAndroid Build Coastguard Worker  You can tell curl to perform optional commands both before and/or after a
497*6236dae4SAndroid Build Coastguard Worker  file transfer. Study the -Q/--quote option.
498*6236dae4SAndroid Build Coastguard Worker
499*6236dae4SAndroid Build Coastguard Worker  Since curl is used for file transfers, you do not normally use curl to
500*6236dae4SAndroid Build Coastguard Worker  perform FTP commands without transferring anything. Therefore you must
501*6236dae4SAndroid Build Coastguard Worker  always specify a URL to transfer to/from even when doing custom FTP
502*6236dae4SAndroid Build Coastguard Worker  commands, or use -I which implies the "no body" option sent to libcurl.
503*6236dae4SAndroid Build Coastguard Worker
504*6236dae4SAndroid Build Coastguard Worker  3.5 How can I disable the Accept: */* header?
505*6236dae4SAndroid Build Coastguard Worker
506*6236dae4SAndroid Build Coastguard Worker  You can change all internally generated headers by adding a replacement with
507*6236dae4SAndroid Build Coastguard Worker  the -H/--header option. By adding a header with empty contents you safely
508*6236dae4SAndroid Build Coastguard Worker  disable that one. Use -H "Accept:" to disable that specific header.
509*6236dae4SAndroid Build Coastguard Worker
510*6236dae4SAndroid Build Coastguard Worker  3.6 Does curl support ASP, XML, XHTML or HTML version Y?
511*6236dae4SAndroid Build Coastguard Worker
512*6236dae4SAndroid Build Coastguard Worker  To curl, all contents are alike. It does not matter how the page was
513*6236dae4SAndroid Build Coastguard Worker  generated. It may be ASP, PHP, Perl, shell-script, SSI or plain HTML
514*6236dae4SAndroid Build Coastguard Worker  files. There is no difference to curl and it does not even know what kind of
515*6236dae4SAndroid Build Coastguard Worker  language that generated the page.
516*6236dae4SAndroid Build Coastguard Worker
517*6236dae4SAndroid Build Coastguard Worker  See also item 3.14 regarding JavaScript.
518*6236dae4SAndroid Build Coastguard Worker
519*6236dae4SAndroid Build Coastguard Worker  3.7 Can I use curl to delete/rename a file through FTP?
520*6236dae4SAndroid Build Coastguard Worker
521*6236dae4SAndroid Build Coastguard Worker  Yes. You specify custom FTP commands with -Q/--quote.
522*6236dae4SAndroid Build Coastguard Worker
523*6236dae4SAndroid Build Coastguard Worker  One example would be to delete a file after you have downloaded it:
524*6236dae4SAndroid Build Coastguard Worker
525*6236dae4SAndroid Build Coastguard Worker     curl -O ftp://example.com/coolfile -Q '-DELE coolfile'
526*6236dae4SAndroid Build Coastguard Worker
527*6236dae4SAndroid Build Coastguard Worker  or rename a file after upload:
528*6236dae4SAndroid Build Coastguard Worker
529*6236dae4SAndroid Build Coastguard Worker     curl -T infile ftp://example.com/dir/ -Q "-RNFR infile" -Q "-RNTO newname"
530*6236dae4SAndroid Build Coastguard Worker
531*6236dae4SAndroid Build Coastguard Worker  3.8 How do I tell curl to follow HTTP redirects?
532*6236dae4SAndroid Build Coastguard Worker
533*6236dae4SAndroid Build Coastguard Worker  curl does not follow so-called redirects by default. The Location: header
534*6236dae4SAndroid Build Coastguard Worker  that informs the client about this is only interpreted if you are using the
535*6236dae4SAndroid Build Coastguard Worker  -L/--location option. As in:
536*6236dae4SAndroid Build Coastguard Worker
537*6236dae4SAndroid Build Coastguard Worker     curl -L http://example.com
538*6236dae4SAndroid Build Coastguard Worker
539*6236dae4SAndroid Build Coastguard Worker  Not all redirects are HTTP ones, see 4.14
540*6236dae4SAndroid Build Coastguard Worker
541*6236dae4SAndroid Build Coastguard Worker  3.9 How do I use curl in my favorite programming language?
542*6236dae4SAndroid Build Coastguard Worker
543*6236dae4SAndroid Build Coastguard Worker  Many programming languages have interfaces/bindings that allow you to use
544*6236dae4SAndroid Build Coastguard Worker  curl without having to use the command line tool. If you are fluent in such
545*6236dae4SAndroid Build Coastguard Worker  a language, you may prefer to use one of these interfaces instead.
546*6236dae4SAndroid Build Coastguard Worker
547*6236dae4SAndroid Build Coastguard Worker  Find out more about which languages that support curl directly, and how to
548*6236dae4SAndroid Build Coastguard Worker  install and use them, in the libcurl section of the curl website:
549*6236dae4SAndroid Build Coastguard Worker  https://curl.se/libcurl/
550*6236dae4SAndroid Build Coastguard Worker
551*6236dae4SAndroid Build Coastguard Worker  All the various bindings to libcurl are made by other projects and people,
552*6236dae4SAndroid Build Coastguard Worker  outside of the cURL project. The cURL project itself only produces libcurl
553*6236dae4SAndroid Build Coastguard Worker  with its plain C API. If you do not find anywhere else to ask you can ask
554*6236dae4SAndroid Build Coastguard Worker  about bindings on the curl-library list too, but be prepared that people on
555*6236dae4SAndroid Build Coastguard Worker  that list may not know anything about bindings.
556*6236dae4SAndroid Build Coastguard Worker
557*6236dae4SAndroid Build Coastguard Worker  In December 2021, there were interfaces available for the following
558*6236dae4SAndroid Build Coastguard Worker  languages: Ada95, Basic, C, C++, Ch, Cocoa, D, Delphi, Dylan, Eiffel,
559*6236dae4SAndroid Build Coastguard Worker  Euphoria, Falcon, Ferite, Gambas, glib/GTK+, Go, Guile, Harbour, Haskell,
560*6236dae4SAndroid Build Coastguard Worker  Java, Julia, Lisp, Lua, Mono, .NET, node.js, Object-Pascal, OCaml, Pascal,
561*6236dae4SAndroid Build Coastguard Worker  Perl, PHP, PostgreSQL, Python, R, Rexx, Ring, RPG, Ruby, Rust, Scheme,
562*6236dae4SAndroid Build Coastguard Worker  Scilab, S-Lang, Smalltalk, SP-Forth, SPL, Tcl, Visual Basic, Visual FoxPro,
563*6236dae4SAndroid Build Coastguard Worker  Q, wxwidgets, XBLite and Xoho. By the time you read this, additional ones
564*6236dae4SAndroid Build Coastguard Worker  may have appeared.
565*6236dae4SAndroid Build Coastguard Worker
566*6236dae4SAndroid Build Coastguard Worker  3.10 What about SOAP, WebDAV, XML-RPC or similar protocols over HTTP?
567*6236dae4SAndroid Build Coastguard Worker
568*6236dae4SAndroid Build Coastguard Worker  curl adheres to the HTTP spec, which basically means you can play with *any*
569*6236dae4SAndroid Build Coastguard Worker  protocol that is built on top of HTTP. Protocols such as SOAP, WebDAV and
570*6236dae4SAndroid Build Coastguard Worker  XML-RPC are all such ones. You can use -X to set custom requests and -H to
571*6236dae4SAndroid Build Coastguard Worker  set custom headers (or replace internally generated ones).
572*6236dae4SAndroid Build Coastguard Worker
573*6236dae4SAndroid Build Coastguard Worker  Using libcurl is of course just as good and you would just use the proper
574*6236dae4SAndroid Build Coastguard Worker  library options to do the same.
575*6236dae4SAndroid Build Coastguard Worker
576*6236dae4SAndroid Build Coastguard Worker  3.11 How do I POST with a different Content-Type?
577*6236dae4SAndroid Build Coastguard Worker
578*6236dae4SAndroid Build Coastguard Worker  You can always replace the internally generated headers with -H/--header.
579*6236dae4SAndroid Build Coastguard Worker  To make a simple HTTP POST with text/xml as content-type, do something like:
580*6236dae4SAndroid Build Coastguard Worker
581*6236dae4SAndroid Build Coastguard Worker        curl -d "datatopost" -H "Content-Type: text/xml" [URL]
582*6236dae4SAndroid Build Coastguard Worker
583*6236dae4SAndroid Build Coastguard Worker  3.12 Why do FTP-specific features over HTTP proxy fail?
584*6236dae4SAndroid Build Coastguard Worker
585*6236dae4SAndroid Build Coastguard Worker  Because when you use an HTTP proxy, the protocol spoken on the network will
586*6236dae4SAndroid Build Coastguard Worker  be HTTP, even if you specify an FTP URL. This effectively means that you
587*6236dae4SAndroid Build Coastguard Worker  normally cannot use FTP-specific features such as FTP upload and FTP quote
588*6236dae4SAndroid Build Coastguard Worker  etc.
589*6236dae4SAndroid Build Coastguard Worker
590*6236dae4SAndroid Build Coastguard Worker  There is one exception to this rule, and that is if you can "tunnel through"
591*6236dae4SAndroid Build Coastguard Worker  the given HTTP proxy. Proxy tunneling is enabled with a special option (-p)
592*6236dae4SAndroid Build Coastguard Worker  and is generally not available as proxy admins usually disable tunneling to
593*6236dae4SAndroid Build Coastguard Worker  ports other than 443 (which is used for HTTPS access through proxies).
594*6236dae4SAndroid Build Coastguard Worker
595*6236dae4SAndroid Build Coastguard Worker  3.13 Why do my single/double quotes fail?
596*6236dae4SAndroid Build Coastguard Worker
597*6236dae4SAndroid Build Coastguard Worker  To specify a command line option that includes spaces, you might need to
598*6236dae4SAndroid Build Coastguard Worker  put the entire option within quotes. Like in:
599*6236dae4SAndroid Build Coastguard Worker
600*6236dae4SAndroid Build Coastguard Worker   curl -d " with spaces " example.com
601*6236dae4SAndroid Build Coastguard Worker
602*6236dae4SAndroid Build Coastguard Worker  or perhaps
603*6236dae4SAndroid Build Coastguard Worker
604*6236dae4SAndroid Build Coastguard Worker   curl -d ' with spaces ' example.com
605*6236dae4SAndroid Build Coastguard Worker
606*6236dae4SAndroid Build Coastguard Worker  Exactly what kind of quotes and how to do this is entirely up to the shell
607*6236dae4SAndroid Build Coastguard Worker  or command line interpreter that you are using. For most Unix shells, you
608*6236dae4SAndroid Build Coastguard Worker  can more or less pick either single (') or double (") quotes. For
609*6236dae4SAndroid Build Coastguard Worker  Windows/DOS command prompts you must use double (") quotes, and if the
610*6236dae4SAndroid Build Coastguard Worker  option string contains inner double quotes you can escape them with a
611*6236dae4SAndroid Build Coastguard Worker  backslash.
612*6236dae4SAndroid Build Coastguard Worker
613*6236dae4SAndroid Build Coastguard Worker  For Windows powershell the arguments are not always passed on as expected
614*6236dae4SAndroid Build Coastguard Worker  because curl is not a powershell script. You may or may not be able to use
615*6236dae4SAndroid Build Coastguard Worker  single quotes. To escape inner double quotes seems to require a
616*6236dae4SAndroid Build Coastguard Worker  backslash-backtick escape sequence and the outer quotes as double quotes.
617*6236dae4SAndroid Build Coastguard Worker
618*6236dae4SAndroid Build Coastguard Worker  Please study the documentation for your particular environment. Examples in
619*6236dae4SAndroid Build Coastguard Worker  the curl docs will use a mix of both of these as shown above. You must
620*6236dae4SAndroid Build Coastguard Worker  adjust them to work in your environment.
621*6236dae4SAndroid Build Coastguard Worker
622*6236dae4SAndroid Build Coastguard Worker  Remember that curl works and runs on more operating systems than most single
623*6236dae4SAndroid Build Coastguard Worker  individuals have ever tried.
624*6236dae4SAndroid Build Coastguard Worker
625*6236dae4SAndroid Build Coastguard Worker  3.14 Does curl support JavaScript or PAC (automated proxy config)?
626*6236dae4SAndroid Build Coastguard Worker
627*6236dae4SAndroid Build Coastguard Worker  Many webpages do magic stuff using embedded JavaScript. curl and libcurl
628*6236dae4SAndroid Build Coastguard Worker  have no built-in support for that, so it will be treated just like any other
629*6236dae4SAndroid Build Coastguard Worker  contents.
630*6236dae4SAndroid Build Coastguard Worker
631*6236dae4SAndroid Build Coastguard Worker  .pac files are a Netscape invention and are sometimes used by organizations
632*6236dae4SAndroid Build Coastguard Worker  to allow them to differentiate which proxies to use. The .pac contents is
633*6236dae4SAndroid Build Coastguard Worker  just a JavaScript program that gets invoked by the browser and that returns
634*6236dae4SAndroid Build Coastguard Worker  the name of the proxy to connect to. Since curl does not support JavaScript,
635*6236dae4SAndroid Build Coastguard Worker  it cannot support .pac proxy configuration either.
636*6236dae4SAndroid Build Coastguard Worker
637*6236dae4SAndroid Build Coastguard Worker  Some workarounds usually suggested to overcome this JavaScript dependency:
638*6236dae4SAndroid Build Coastguard Worker
639*6236dae4SAndroid Build Coastguard Worker  Depending on the JavaScript complexity, write up a script that translates it
640*6236dae4SAndroid Build Coastguard Worker  to another language and execute that.
641*6236dae4SAndroid Build Coastguard Worker
642*6236dae4SAndroid Build Coastguard Worker  Read the JavaScript code and rewrite the same logic in another language.
643*6236dae4SAndroid Build Coastguard Worker
644*6236dae4SAndroid Build Coastguard Worker  Implement a JavaScript interpreter, people have successfully used the
645*6236dae4SAndroid Build Coastguard Worker  Mozilla JavaScript engine in the past.
646*6236dae4SAndroid Build Coastguard Worker
647*6236dae4SAndroid Build Coastguard Worker  Ask your admins to stop this, for a static proxy setup or similar.
648*6236dae4SAndroid Build Coastguard Worker
649*6236dae4SAndroid Build Coastguard Worker  3.15 Can I do recursive fetches with curl?
650*6236dae4SAndroid Build Coastguard Worker
651*6236dae4SAndroid Build Coastguard Worker  No. curl itself has no code that performs recursive operations, such as
652*6236dae4SAndroid Build Coastguard Worker  those performed by wget and similar tools.
653*6236dae4SAndroid Build Coastguard Worker
654*6236dae4SAndroid Build Coastguard Worker  There exists wrapper scripts with that functionality (for example the
655*6236dae4SAndroid Build Coastguard Worker  curlmirror perl script), and you can write programs based on libcurl to do
656*6236dae4SAndroid Build Coastguard Worker  it, but the command line tool curl itself cannot.
657*6236dae4SAndroid Build Coastguard Worker
658*6236dae4SAndroid Build Coastguard Worker  3.16 What certificates do I need when I use SSL?
659*6236dae4SAndroid Build Coastguard Worker
660*6236dae4SAndroid Build Coastguard Worker  There are three different kinds of "certificates" to keep track of when we
661*6236dae4SAndroid Build Coastguard Worker  talk about using SSL-based protocols (HTTPS or FTPS) using curl or libcurl.
662*6236dae4SAndroid Build Coastguard Worker
663*6236dae4SAndroid Build Coastguard Worker  CLIENT CERTIFICATE
664*6236dae4SAndroid Build Coastguard Worker
665*6236dae4SAndroid Build Coastguard Worker  The server you communicate with may require that you can provide this in
666*6236dae4SAndroid Build Coastguard Worker  order to prove that you actually are who you claim to be. If the server
667*6236dae4SAndroid Build Coastguard Worker  does not require this, you do not need a client certificate.
668*6236dae4SAndroid Build Coastguard Worker
669*6236dae4SAndroid Build Coastguard Worker  A client certificate is always used together with a private key, and the
670*6236dae4SAndroid Build Coastguard Worker  private key has a pass phrase that protects it.
671*6236dae4SAndroid Build Coastguard Worker
672*6236dae4SAndroid Build Coastguard Worker  SERVER CERTIFICATE
673*6236dae4SAndroid Build Coastguard Worker
674*6236dae4SAndroid Build Coastguard Worker  The server you communicate with has a server certificate. You can and should
675*6236dae4SAndroid Build Coastguard Worker  verify this certificate to make sure that you are truly talking to the real
676*6236dae4SAndroid Build Coastguard Worker  server and not a server impersonating it.
677*6236dae4SAndroid Build Coastguard Worker
678*6236dae4SAndroid Build Coastguard Worker  CERTIFICATE AUTHORITY CERTIFICATE ("CA cert")
679*6236dae4SAndroid Build Coastguard Worker
680*6236dae4SAndroid Build Coastguard Worker  You often have several CA certs in a CA cert bundle that can be used to
681*6236dae4SAndroid Build Coastguard Worker  verify a server certificate that was signed by one of the authorities in the
682*6236dae4SAndroid Build Coastguard Worker  bundle. curl does not come with a CA cert bundle but most curl installs
683*6236dae4SAndroid Build Coastguard Worker  provide one. You can also override the default.
684*6236dae4SAndroid Build Coastguard Worker
685*6236dae4SAndroid Build Coastguard Worker  The server certificate verification process is made by using a Certificate
686*6236dae4SAndroid Build Coastguard Worker  Authority certificate ("CA cert") that was used to sign the server
687*6236dae4SAndroid Build Coastguard Worker  certificate. Server certificate verification is enabled by default in curl
688*6236dae4SAndroid Build Coastguard Worker  and libcurl and is often the reason for problems as explained in FAQ entry
689*6236dae4SAndroid Build Coastguard Worker  4.12 and the SSLCERTS document
690*6236dae4SAndroid Build Coastguard Worker  (https://curl.se/docs/sslcerts.html). Server certificates that are
691*6236dae4SAndroid Build Coastguard Worker  "self-signed" or otherwise signed by a CA that you do not have a CA cert
692*6236dae4SAndroid Build Coastguard Worker  for, cannot be verified. If the verification during a connect fails, you are
693*6236dae4SAndroid Build Coastguard Worker  refused access. You then need to explicitly disable the verification to
694*6236dae4SAndroid Build Coastguard Worker  connect to the server.
695*6236dae4SAndroid Build Coastguard Worker
696*6236dae4SAndroid Build Coastguard Worker  3.17 How do I list the root directory of an FTP server?
697*6236dae4SAndroid Build Coastguard Worker
698*6236dae4SAndroid Build Coastguard Worker  There are two ways. The way defined in the RFC is to use an encoded slash
699*6236dae4SAndroid Build Coastguard Worker  in the first path part. List the "/tmp" directory like this:
700*6236dae4SAndroid Build Coastguard Worker
701*6236dae4SAndroid Build Coastguard Worker     curl ftp://ftp.example.com/%2ftmp/
702*6236dae4SAndroid Build Coastguard Worker
703*6236dae4SAndroid Build Coastguard Worker  or the not-quite-kosher-but-more-readable way, by simply starting the path
704*6236dae4SAndroid Build Coastguard Worker  section of the URL with a slash:
705*6236dae4SAndroid Build Coastguard Worker
706*6236dae4SAndroid Build Coastguard Worker     curl ftp://ftp.example.com//tmp/
707*6236dae4SAndroid Build Coastguard Worker
708*6236dae4SAndroid Build Coastguard Worker  3.18 Can I use curl to send a POST/PUT and not wait for a response?
709*6236dae4SAndroid Build Coastguard Worker
710*6236dae4SAndroid Build Coastguard Worker  No.
711*6236dae4SAndroid Build Coastguard Worker
712*6236dae4SAndroid Build Coastguard Worker  You can easily write your own program using libcurl to do such stunts.
713*6236dae4SAndroid Build Coastguard Worker
714*6236dae4SAndroid Build Coastguard Worker  3.19 How do I get HTTP from a host using a specific IP address?
715*6236dae4SAndroid Build Coastguard Worker
716*6236dae4SAndroid Build Coastguard Worker  For example, you may be trying out a website installation that is not yet in
717*6236dae4SAndroid Build Coastguard Worker  the DNS. Or you have a site using multiple IP addresses for a given host
718*6236dae4SAndroid Build Coastguard Worker  name and you want to address a specific one out of the set.
719*6236dae4SAndroid Build Coastguard Worker
720*6236dae4SAndroid Build Coastguard Worker  Set a custom Host: header that identifies the server name you want to reach
721*6236dae4SAndroid Build Coastguard Worker  but use the target IP address in the URL:
722*6236dae4SAndroid Build Coastguard Worker
723*6236dae4SAndroid Build Coastguard Worker    curl --header "Host: www.example.com" http://127.0.0.1/
724*6236dae4SAndroid Build Coastguard Worker
725*6236dae4SAndroid Build Coastguard Worker  You can also opt to add faked hostname entries to curl with the --resolve
726*6236dae4SAndroid Build Coastguard Worker  option. That has the added benefit that things like redirects will also work
727*6236dae4SAndroid Build Coastguard Worker  properly. The above operation would instead be done as:
728*6236dae4SAndroid Build Coastguard Worker
729*6236dae4SAndroid Build Coastguard Worker    curl --resolve www.example.com:80:127.0.0.1 http://www.example.com/
730*6236dae4SAndroid Build Coastguard Worker
731*6236dae4SAndroid Build Coastguard Worker  3.20 How to SFTP from my user's home directory?
732*6236dae4SAndroid Build Coastguard Worker
733*6236dae4SAndroid Build Coastguard Worker  Contrary to how FTP works, SFTP and SCP URLs specify the exact directory to
734*6236dae4SAndroid Build Coastguard Worker  work with. It means that if you do not specify that you want the user's home
735*6236dae4SAndroid Build Coastguard Worker  directory, you get the actual root directory.
736*6236dae4SAndroid Build Coastguard Worker
737*6236dae4SAndroid Build Coastguard Worker  To specify a file in your user's home directory, you need to use the correct
738*6236dae4SAndroid Build Coastguard Worker  URL syntax which for SFTP might look similar to:
739*6236dae4SAndroid Build Coastguard Worker
740*6236dae4SAndroid Build Coastguard Worker    curl -O -u user:password sftp://example.com/~/file.txt
741*6236dae4SAndroid Build Coastguard Worker
742*6236dae4SAndroid Build Coastguard Worker  and for SCP it is just a different protocol prefix:
743*6236dae4SAndroid Build Coastguard Worker
744*6236dae4SAndroid Build Coastguard Worker    curl -O -u user:password scp://example.com/~/file.txt
745*6236dae4SAndroid Build Coastguard Worker
746*6236dae4SAndroid Build Coastguard Worker  3.21 Protocol xxx not supported or disabled in libcurl
747*6236dae4SAndroid Build Coastguard Worker
748*6236dae4SAndroid Build Coastguard Worker  When passing on a URL to curl to use, it may respond that the particular
749*6236dae4SAndroid Build Coastguard Worker  protocol is not supported or disabled. The particular way this error message
750*6236dae4SAndroid Build Coastguard Worker  is phrased is because curl does not make a distinction internally of whether
751*6236dae4SAndroid Build Coastguard Worker  a particular protocol is not supported (i.e. never got any code added that
752*6236dae4SAndroid Build Coastguard Worker  knows how to speak that protocol) or if it was explicitly disabled. curl can
753*6236dae4SAndroid Build Coastguard Worker  be built to only support a given set of protocols, and the rest would then
754*6236dae4SAndroid Build Coastguard Worker  be disabled or not supported.
755*6236dae4SAndroid Build Coastguard Worker
756*6236dae4SAndroid Build Coastguard Worker  Note that this error will also occur if you pass a wrongly spelled protocol
757*6236dae4SAndroid Build Coastguard Worker  part as in "htpt://example.com" or as in the less evident case if you prefix
758*6236dae4SAndroid Build Coastguard Worker  the protocol part with a space as in " http://example.com/".
759*6236dae4SAndroid Build Coastguard Worker
760*6236dae4SAndroid Build Coastguard Worker  3.22 curl -X gives me HTTP problems
761*6236dae4SAndroid Build Coastguard Worker
762*6236dae4SAndroid Build Coastguard Worker  In normal circumstances, -X should hardly ever be used.
763*6236dae4SAndroid Build Coastguard Worker
764*6236dae4SAndroid Build Coastguard Worker  By default you use curl without explicitly saying which request method to
765*6236dae4SAndroid Build Coastguard Worker  use when the URL identifies an HTTP transfer. If you just pass in a URL like
766*6236dae4SAndroid Build Coastguard Worker  "curl http://example.com" it will use GET. If you use -d or -F curl will use
767*6236dae4SAndroid Build Coastguard Worker  POST, -I will cause a HEAD and -T will make it a PUT.
768*6236dae4SAndroid Build Coastguard Worker
769*6236dae4SAndroid Build Coastguard Worker  If for whatever reason you are not happy with these default choices that curl
770*6236dae4SAndroid Build Coastguard Worker  does for you, you can override those request methods by specifying -X
771*6236dae4SAndroid Build Coastguard Worker  [WHATEVER]. This way you can for example send a DELETE by doing "curl -X
772*6236dae4SAndroid Build Coastguard Worker  DELETE [URL]".
773*6236dae4SAndroid Build Coastguard Worker
774*6236dae4SAndroid Build Coastguard Worker  It is thus pointless to do "curl -XGET [URL]" as GET would be used anyway.
775*6236dae4SAndroid Build Coastguard Worker  In the same vein it is pointless to do "curl -X POST -d data [URL]". You can
776*6236dae4SAndroid Build Coastguard Worker  make a fun and somewhat rare request that sends a request-body in a GET
777*6236dae4SAndroid Build Coastguard Worker  request with something like "curl -X GET -d data [URL]"
778*6236dae4SAndroid Build Coastguard Worker
779*6236dae4SAndroid Build Coastguard Worker  Note that -X does not actually change curl's behavior as it only modifies the
780*6236dae4SAndroid Build Coastguard Worker  actual string sent in the request, but that may of course trigger a
781*6236dae4SAndroid Build Coastguard Worker  different set of events.
782*6236dae4SAndroid Build Coastguard Worker
783*6236dae4SAndroid Build Coastguard Worker  Accordingly, by using -XPOST on a command line that for example would follow
784*6236dae4SAndroid Build Coastguard Worker  a 303 redirect, you will effectively prevent curl from behaving
785*6236dae4SAndroid Build Coastguard Worker  correctly. Be aware.
786*6236dae4SAndroid Build Coastguard Worker
787*6236dae4SAndroid Build Coastguard Worker
788*6236dae4SAndroid Build Coastguard Worker4. Running Problems
789*6236dae4SAndroid Build Coastguard Worker
790*6236dae4SAndroid Build Coastguard Worker  4.2 Why do I get problems when I use & or % in the URL?
791*6236dae4SAndroid Build Coastguard Worker
792*6236dae4SAndroid Build Coastguard Worker  In general Unix shells, the & symbol is treated specially and when used, it
793*6236dae4SAndroid Build Coastguard Worker  runs the specified command in the background. To safely send the & as a part
794*6236dae4SAndroid Build Coastguard Worker  of a URL, you should quote the entire URL by using single (') or double (")
795*6236dae4SAndroid Build Coastguard Worker  quotes around it. Similar problems can also occur on some shells with other
796*6236dae4SAndroid Build Coastguard Worker  characters, including ?*!$~(){}<>\|;`. When in doubt, quote the URL.
797*6236dae4SAndroid Build Coastguard Worker
798*6236dae4SAndroid Build Coastguard Worker  An example that would invoke a remote CGI that uses &-symbols could be:
799*6236dae4SAndroid Build Coastguard Worker
800*6236dae4SAndroid Build Coastguard Worker     curl 'http://www.example.com/cgi-bin/query?text=yes&q=curl'
801*6236dae4SAndroid Build Coastguard Worker
802*6236dae4SAndroid Build Coastguard Worker  In Windows, the standard DOS shell treats the percent sign specially and you
803*6236dae4SAndroid Build Coastguard Worker  need to use TWO percent signs for each single one you want to use in the
804*6236dae4SAndroid Build Coastguard Worker  URL.
805*6236dae4SAndroid Build Coastguard Worker
806*6236dae4SAndroid Build Coastguard Worker  If you want a literal percent sign to be part of the data you pass in a POST
807*6236dae4SAndroid Build Coastguard Worker  using -d/--data you must encode it as '%25' (which then also needs the
808*6236dae4SAndroid Build Coastguard Worker  percent sign doubled on Windows machines).
809*6236dae4SAndroid Build Coastguard Worker
810*6236dae4SAndroid Build Coastguard Worker  4.3 How can I use {, }, [ or ] to specify multiple URLs?
811*6236dae4SAndroid Build Coastguard Worker
812*6236dae4SAndroid Build Coastguard Worker  Because those letters have a special meaning to the shell, to be used in
813*6236dae4SAndroid Build Coastguard Worker  a URL specified to curl you must quote them.
814*6236dae4SAndroid Build Coastguard Worker
815*6236dae4SAndroid Build Coastguard Worker  An example that downloads two URLs (sequentially) would be:
816*6236dae4SAndroid Build Coastguard Worker
817*6236dae4SAndroid Build Coastguard Worker    curl '{curl,www}.haxx.se'
818*6236dae4SAndroid Build Coastguard Worker
819*6236dae4SAndroid Build Coastguard Worker  To be able to use those characters as actual parts of the URL (without using
820*6236dae4SAndroid Build Coastguard Worker  them for the curl URL "globbing" system), use the -g/--globoff option:
821*6236dae4SAndroid Build Coastguard Worker
822*6236dae4SAndroid Build Coastguard Worker    curl -g 'www.example.com/weirdname[].html'
823*6236dae4SAndroid Build Coastguard Worker
824*6236dae4SAndroid Build Coastguard Worker  4.4 Why do I get downloaded data even though the webpage does not exist?
825*6236dae4SAndroid Build Coastguard Worker
826*6236dae4SAndroid Build Coastguard Worker  curl asks remote servers for the page you specify. If the page does not exist
827*6236dae4SAndroid Build Coastguard Worker  at the server, the HTTP protocol defines how the server should respond and
828*6236dae4SAndroid Build Coastguard Worker  that means that headers and a "page" will be returned. That is simply how
829*6236dae4SAndroid Build Coastguard Worker  HTTP works.
830*6236dae4SAndroid Build Coastguard Worker
831*6236dae4SAndroid Build Coastguard Worker  By using the --fail option you can tell curl explicitly to not get any data
832*6236dae4SAndroid Build Coastguard Worker  if the HTTP return code does not say success.
833*6236dae4SAndroid Build Coastguard Worker
834*6236dae4SAndroid Build Coastguard Worker  4.5 Why do I get return code XXX from an HTTP server?
835*6236dae4SAndroid Build Coastguard Worker
836*6236dae4SAndroid Build Coastguard Worker  RFC 2616 clearly explains the return codes. This is a short transcript. Go
837*6236dae4SAndroid Build Coastguard Worker  read the RFC for exact details:
838*6236dae4SAndroid Build Coastguard Worker
839*6236dae4SAndroid Build Coastguard Worker    4.5.1 "400 Bad Request"
840*6236dae4SAndroid Build Coastguard Worker
841*6236dae4SAndroid Build Coastguard Worker    The request could not be understood by the server due to malformed
842*6236dae4SAndroid Build Coastguard Worker    syntax. The client SHOULD NOT repeat the request without modifications.
843*6236dae4SAndroid Build Coastguard Worker
844*6236dae4SAndroid Build Coastguard Worker    4.5.2 "401 Unauthorized"
845*6236dae4SAndroid Build Coastguard Worker
846*6236dae4SAndroid Build Coastguard Worker    The request requires user authentication.
847*6236dae4SAndroid Build Coastguard Worker
848*6236dae4SAndroid Build Coastguard Worker    4.5.3 "403 Forbidden"
849*6236dae4SAndroid Build Coastguard Worker
850*6236dae4SAndroid Build Coastguard Worker    The server understood the request, but is refusing to fulfill it.
851*6236dae4SAndroid Build Coastguard Worker    Authorization will not help and the request SHOULD NOT be repeated.
852*6236dae4SAndroid Build Coastguard Worker
853*6236dae4SAndroid Build Coastguard Worker    4.5.4 "404 Not Found"
854*6236dae4SAndroid Build Coastguard Worker
855*6236dae4SAndroid Build Coastguard Worker    The server has not found anything matching the Request-URI. No indication
856*6236dae4SAndroid Build Coastguard Worker    is given as to whether the condition is temporary or permanent.
857*6236dae4SAndroid Build Coastguard Worker
858*6236dae4SAndroid Build Coastguard Worker    4.5.5 "405 Method Not Allowed"
859*6236dae4SAndroid Build Coastguard Worker
860*6236dae4SAndroid Build Coastguard Worker    The method specified in the Request-Line is not allowed for the resource
861*6236dae4SAndroid Build Coastguard Worker    identified by the Request-URI. The response MUST include an Allow header
862*6236dae4SAndroid Build Coastguard Worker    containing a list of valid methods for the requested resource.
863*6236dae4SAndroid Build Coastguard Worker
864*6236dae4SAndroid Build Coastguard Worker    4.5.6 "301 Moved Permanently"
865*6236dae4SAndroid Build Coastguard Worker
866*6236dae4SAndroid Build Coastguard Worker    If you get this return code and an HTML output similar to this:
867*6236dae4SAndroid Build Coastguard Worker
868*6236dae4SAndroid Build Coastguard Worker       <H1>Moved Permanently</H1> The document has moved <A
869*6236dae4SAndroid Build Coastguard Worker       HREF="http://same_url_now_with_a_trailing_slash/">here</A>.
870*6236dae4SAndroid Build Coastguard Worker
871*6236dae4SAndroid Build Coastguard Worker    it might be because you requested a directory URL but without the trailing
872*6236dae4SAndroid Build Coastguard Worker    slash. Try the same operation again _with_ the trailing URL, or use the
873*6236dae4SAndroid Build Coastguard Worker    -L/--location option to follow the redirection.
874*6236dae4SAndroid Build Coastguard Worker
875*6236dae4SAndroid Build Coastguard Worker  4.6 Can you tell me what error code 142 means?
876*6236dae4SAndroid Build Coastguard Worker
877*6236dae4SAndroid Build Coastguard Worker  All curl error codes are described at the end of the man page, in the
878*6236dae4SAndroid Build Coastguard Worker  section called "EXIT CODES".
879*6236dae4SAndroid Build Coastguard Worker
880*6236dae4SAndroid Build Coastguard Worker  Error codes that are larger than the highest documented error code means
881*6236dae4SAndroid Build Coastguard Worker  that curl has exited due to a crash. This is a serious error, and we
882*6236dae4SAndroid Build Coastguard Worker  appreciate a detailed bug report from you that describes how we could go
883*6236dae4SAndroid Build Coastguard Worker  ahead and repeat this.
884*6236dae4SAndroid Build Coastguard Worker
885*6236dae4SAndroid Build Coastguard Worker  4.7 How do I keep usernames and passwords secret in curl command lines?
886*6236dae4SAndroid Build Coastguard Worker
887*6236dae4SAndroid Build Coastguard Worker  This problem has two sides:
888*6236dae4SAndroid Build Coastguard Worker
889*6236dae4SAndroid Build Coastguard Worker  The first part is to avoid having clear-text passwords in the command line
890*6236dae4SAndroid Build Coastguard Worker  so that they do not appear in 'ps' outputs and similar. That is easily
891*6236dae4SAndroid Build Coastguard Worker  avoided by using the "-K" option to tell curl to read parameters from a file
892*6236dae4SAndroid Build Coastguard Worker  or stdin to which you can pass the secret info. curl itself will also
893*6236dae4SAndroid Build Coastguard Worker  attempt to "hide" the given password by blanking out the option - this
894*6236dae4SAndroid Build Coastguard Worker  does not work on all platforms.
895*6236dae4SAndroid Build Coastguard Worker
896*6236dae4SAndroid Build Coastguard Worker  To keep the passwords in your account secret from the rest of the world is
897*6236dae4SAndroid Build Coastguard Worker  not a task that curl addresses. You could of course encrypt them somehow to
898*6236dae4SAndroid Build Coastguard Worker  at least hide them from being read by human eyes, but that is not what
899*6236dae4SAndroid Build Coastguard Worker  anyone would call security.
900*6236dae4SAndroid Build Coastguard Worker
901*6236dae4SAndroid Build Coastguard Worker  Also note that regular HTTP (using Basic authentication) and FTP passwords
902*6236dae4SAndroid Build Coastguard Worker  are sent as cleartext across the network. All it takes for anyone to fetch
903*6236dae4SAndroid Build Coastguard Worker  them is to listen on the network. Eavesdropping is easy. Use more secure
904*6236dae4SAndroid Build Coastguard Worker  authentication methods (like Digest, Negotiate or even NTLM) or consider the
905*6236dae4SAndroid Build Coastguard Worker  SSL-based alternatives HTTPS and FTPS.
906*6236dae4SAndroid Build Coastguard Worker
907*6236dae4SAndroid Build Coastguard Worker  4.8 I found a bug
908*6236dae4SAndroid Build Coastguard Worker
909*6236dae4SAndroid Build Coastguard Worker  It is not a bug if the behavior is documented. Read the docs first.
910*6236dae4SAndroid Build Coastguard Worker  Especially check out the KNOWN_BUGS file, it may be a documented bug.
911*6236dae4SAndroid Build Coastguard Worker
912*6236dae4SAndroid Build Coastguard Worker  If it is a problem with a binary you have downloaded or a package for your
913*6236dae4SAndroid Build Coastguard Worker  particular platform, try contacting the person who built the package/archive
914*6236dae4SAndroid Build Coastguard Worker  you have.
915*6236dae4SAndroid Build Coastguard Worker
916*6236dae4SAndroid Build Coastguard Worker  If there is a bug, read the BUGS document first. Then report it as described
917*6236dae4SAndroid Build Coastguard Worker  in there.
918*6236dae4SAndroid Build Coastguard Worker
919*6236dae4SAndroid Build Coastguard Worker  4.9 curl cannot authenticate to a server that requires NTLM?
920*6236dae4SAndroid Build Coastguard Worker
921*6236dae4SAndroid Build Coastguard Worker  NTLM support requires OpenSSL, GnuTLS, mbedTLS, Secure Transport, or
922*6236dae4SAndroid Build Coastguard Worker  Microsoft Windows libraries at build-time to provide this functionality.
923*6236dae4SAndroid Build Coastguard Worker
924*6236dae4SAndroid Build Coastguard Worker  4.10 My HTTP request using HEAD, PUT or DELETE does not work
925*6236dae4SAndroid Build Coastguard Worker
926*6236dae4SAndroid Build Coastguard Worker  Many web servers allow or demand that the administrator configures the
927*6236dae4SAndroid Build Coastguard Worker  server properly for these requests to work on the web server.
928*6236dae4SAndroid Build Coastguard Worker
929*6236dae4SAndroid Build Coastguard Worker  Some servers seem to support HEAD only on certain kinds of URLs.
930*6236dae4SAndroid Build Coastguard Worker
931*6236dae4SAndroid Build Coastguard Worker  To fully grasp this, try the documentation for the particular server
932*6236dae4SAndroid Build Coastguard Worker  software you are trying to interact with. This is not anything curl can do
933*6236dae4SAndroid Build Coastguard Worker  anything about.
934*6236dae4SAndroid Build Coastguard Worker
935*6236dae4SAndroid Build Coastguard Worker  4.11 Why do my HTTP range requests return the full document?
936*6236dae4SAndroid Build Coastguard Worker
937*6236dae4SAndroid Build Coastguard Worker  Because the range may not be supported by the server, or the server may
938*6236dae4SAndroid Build Coastguard Worker  choose to ignore it and return the full document anyway.
939*6236dae4SAndroid Build Coastguard Worker
940*6236dae4SAndroid Build Coastguard Worker  4.12 Why do I get "certificate verify failed" ?
941*6236dae4SAndroid Build Coastguard Worker
942*6236dae4SAndroid Build Coastguard Worker  When you invoke curl and get an error 60 error back it means that curl
943*6236dae4SAndroid Build Coastguard Worker  could not verify that the server's certificate was good. curl verifies the
944*6236dae4SAndroid Build Coastguard Worker  certificate using the CA cert bundle and verifying for which names the
945*6236dae4SAndroid Build Coastguard Worker  certificate has been granted.
946*6236dae4SAndroid Build Coastguard Worker
947*6236dae4SAndroid Build Coastguard Worker  To completely disable the certificate verification, use -k. This does
948*6236dae4SAndroid Build Coastguard Worker  however enable man-in-the-middle attacks and makes the transfer INSECURE.
949*6236dae4SAndroid Build Coastguard Worker  We strongly advise against doing this for more than experiments.
950*6236dae4SAndroid Build Coastguard Worker
951*6236dae4SAndroid Build Coastguard Worker  If you get this failure with a CA cert bundle installed and used, the
952*6236dae4SAndroid Build Coastguard Worker  server's certificate might not be signed by one of the CA's in your CA
953*6236dae4SAndroid Build Coastguard Worker  store. It might for example be self-signed. You then correct this problem by
954*6236dae4SAndroid Build Coastguard Worker  obtaining a valid CA cert for the server. Or again, decrease the security by
955*6236dae4SAndroid Build Coastguard Worker  disabling this check.
956*6236dae4SAndroid Build Coastguard Worker
957*6236dae4SAndroid Build Coastguard Worker  At times, you find that the verification works in your favorite browser but
958*6236dae4SAndroid Build Coastguard Worker  fails in curl. When this happens, the reason is usually that the server
959*6236dae4SAndroid Build Coastguard Worker  sends an incomplete cert chain. The server is mandated to send all
960*6236dae4SAndroid Build Coastguard Worker  "intermediate certificates" but does not. This typically works with browsers
961*6236dae4SAndroid Build Coastguard Worker  anyway since they A) cache such certs and B) supports AIA which downloads
962*6236dae4SAndroid Build Coastguard Worker  such missing certificates on demand. This is a server misconfiguration. A
963*6236dae4SAndroid Build Coastguard Worker  good way to figure out if this is the case it to use the SSL Labs server
964*6236dae4SAndroid Build Coastguard Worker  test and check the certificate chain: https://www.ssllabs.com/ssltest/
965*6236dae4SAndroid Build Coastguard Worker
966*6236dae4SAndroid Build Coastguard Worker  Details are also in the SSLCERTS.md document, found online here:
967*6236dae4SAndroid Build Coastguard Worker  https://curl.se/docs/sslcerts.html
968*6236dae4SAndroid Build Coastguard Worker
969*6236dae4SAndroid Build Coastguard Worker  4.13 Why is curl -R on Windows one hour off?
970*6236dae4SAndroid Build Coastguard Worker
971*6236dae4SAndroid Build Coastguard Worker  Since curl 7.53.0 this issue should be fixed as long as curl was built with
972*6236dae4SAndroid Build Coastguard Worker  any modern compiler that allows for a 64-bit curl_off_t type. For older
973*6236dae4SAndroid Build Coastguard Worker  compilers or prior curl versions it may set a time that appears one hour off.
974*6236dae4SAndroid Build Coastguard Worker  This happens due to a flaw in how Windows stores and uses file modification
975*6236dae4SAndroid Build Coastguard Worker  times and it is not easily worked around. For more details read this:
976*6236dae4SAndroid Build Coastguard Worker  https://www.codeproject.com/Articles/1144/Beating-the-Daylight-Savings-Time-bug-and-getting
977*6236dae4SAndroid Build Coastguard Worker
978*6236dae4SAndroid Build Coastguard Worker  4.14 Redirects work in browser but not with curl
979*6236dae4SAndroid Build Coastguard Worker
980*6236dae4SAndroid Build Coastguard Worker  curl supports HTTP redirects well (see item 3.8). Browsers generally support
981*6236dae4SAndroid Build Coastguard Worker  at least two other ways to perform redirects that curl does not:
982*6236dae4SAndroid Build Coastguard Worker
983*6236dae4SAndroid Build Coastguard Worker  Meta tags. You can write an HTML tag that will cause the browser to redirect
984*6236dae4SAndroid Build Coastguard Worker  to another given URL after a certain time.
985*6236dae4SAndroid Build Coastguard Worker
986*6236dae4SAndroid Build Coastguard Worker  JavaScript. You can write a JavaScript program embedded in an HTML page that
987*6236dae4SAndroid Build Coastguard Worker  redirects the browser to another given URL.
988*6236dae4SAndroid Build Coastguard Worker
989*6236dae4SAndroid Build Coastguard Worker  There is no way to make curl follow these redirects. You must either
990*6236dae4SAndroid Build Coastguard Worker  manually figure out what the page is set to do, or write a script that parses
991*6236dae4SAndroid Build Coastguard Worker  the results and fetches the new URL.
992*6236dae4SAndroid Build Coastguard Worker
993*6236dae4SAndroid Build Coastguard Worker  4.15 FTPS does not work
994*6236dae4SAndroid Build Coastguard Worker
995*6236dae4SAndroid Build Coastguard Worker  curl supports FTPS (sometimes known as FTP-SSL) both implicit and explicit
996*6236dae4SAndroid Build Coastguard Worker  mode.
997*6236dae4SAndroid Build Coastguard Worker
998*6236dae4SAndroid Build Coastguard Worker  When a URL is used that starts with FTPS://, curl assumes implicit SSL on
999*6236dae4SAndroid Build Coastguard Worker  the control connection and will therefore immediately connect and try to
1000*6236dae4SAndroid Build Coastguard Worker  speak SSL. FTPS:// connections default to port 990.
1001*6236dae4SAndroid Build Coastguard Worker
1002*6236dae4SAndroid Build Coastguard Worker  To use explicit FTPS, you use an FTP:// URL and the --ftp-ssl option (or one
1003*6236dae4SAndroid Build Coastguard Worker  of its related flavors). This is the most common method, and the one
1004*6236dae4SAndroid Build Coastguard Worker  mandated by RFC 4217. This kind of connection will then of course use the
1005*6236dae4SAndroid Build Coastguard Worker  standard FTP port 21 by default.
1006*6236dae4SAndroid Build Coastguard Worker
1007*6236dae4SAndroid Build Coastguard Worker  4.16 My HTTP POST or PUT requests are slow
1008*6236dae4SAndroid Build Coastguard Worker
1009*6236dae4SAndroid Build Coastguard Worker  libcurl makes all POST and PUT requests (except for requests with a small
1010*6236dae4SAndroid Build Coastguard Worker  request body) use the "Expect: 100-continue" header. This header allows the
1011*6236dae4SAndroid Build Coastguard Worker  server to deny the operation early so that libcurl can bail out before having
1012*6236dae4SAndroid Build Coastguard Worker  to send any data. This is useful in authentication cases and others.
1013*6236dae4SAndroid Build Coastguard Worker
1014*6236dae4SAndroid Build Coastguard Worker  However, many servers do not implement the Expect: stuff properly and if the
1015*6236dae4SAndroid Build Coastguard Worker  server does not respond (positively) within 1 second libcurl will continue
1016*6236dae4SAndroid Build Coastguard Worker  and send off the data anyway.
1017*6236dae4SAndroid Build Coastguard Worker
1018*6236dae4SAndroid Build Coastguard Worker  You can disable libcurl's use of the Expect: header the same way you disable
1019*6236dae4SAndroid Build Coastguard Worker  any header, using -H / CURLOPT_HTTPHEADER, or by forcing it to use HTTP 1.0.
1020*6236dae4SAndroid Build Coastguard Worker
1021*6236dae4SAndroid Build Coastguard Worker  4.17 Non-functional connect timeouts
1022*6236dae4SAndroid Build Coastguard Worker
1023*6236dae4SAndroid Build Coastguard Worker  In most Windows setups having a timeout longer than 21 seconds make no
1024*6236dae4SAndroid Build Coastguard Worker  difference, as it will only send 3 TCP SYN packets and no more. The second
1025*6236dae4SAndroid Build Coastguard Worker  packet sent three seconds after the first and the third six seconds after
1026*6236dae4SAndroid Build Coastguard Worker  the second. No more than three packets are sent, no matter how long the
1027*6236dae4SAndroid Build Coastguard Worker  timeout is set.
1028*6236dae4SAndroid Build Coastguard Worker
1029*6236dae4SAndroid Build Coastguard Worker  See option TcpMaxConnectRetransmissions on this page:
1030*6236dae4SAndroid Build Coastguard Worker  https://support.microsoft.com/en-us/kb/175523/en-us
1031*6236dae4SAndroid Build Coastguard Worker
1032*6236dae4SAndroid Build Coastguard Worker  Also, even on non-Windows systems there may run a firewall or anti-virus
1033*6236dae4SAndroid Build Coastguard Worker  software or similar that accepts the connection but does not actually do
1034*6236dae4SAndroid Build Coastguard Worker  anything else. This will make (lib)curl to consider the connection connected
1035*6236dae4SAndroid Build Coastguard Worker  and thus the connect timeout will not trigger.
1036*6236dae4SAndroid Build Coastguard Worker
1037*6236dae4SAndroid Build Coastguard Worker  4.18 file:// URLs containing drive letters (Windows, NetWare)
1038*6236dae4SAndroid Build Coastguard Worker
1039*6236dae4SAndroid Build Coastguard Worker  When using curl to try to download a local file, one might use a URL
1040*6236dae4SAndroid Build Coastguard Worker  in this format:
1041*6236dae4SAndroid Build Coastguard Worker
1042*6236dae4SAndroid Build Coastguard Worker  file://D:/blah.txt
1043*6236dae4SAndroid Build Coastguard Worker
1044*6236dae4SAndroid Build Coastguard Worker  you will find that even if D:\blah.txt does exist, curl returns a 'file
1045*6236dae4SAndroid Build Coastguard Worker  not found' error.
1046*6236dae4SAndroid Build Coastguard Worker
1047*6236dae4SAndroid Build Coastguard Worker  According to RFC 1738 (https://www.ietf.org/rfc/rfc1738.txt),
1048*6236dae4SAndroid Build Coastguard Worker  file:// URLs must contain a host component, but it is ignored by
1049*6236dae4SAndroid Build Coastguard Worker  most implementations. In the above example, 'D:' is treated as the
1050*6236dae4SAndroid Build Coastguard Worker  host component, and is taken away. Thus, curl tries to open '/blah.txt'.
1051*6236dae4SAndroid Build Coastguard Worker  If your system is installed to drive C:, that will resolve to 'C:\blah.txt',
1052*6236dae4SAndroid Build Coastguard Worker  and if that does not exist you will get the not found error.
1053*6236dae4SAndroid Build Coastguard Worker
1054*6236dae4SAndroid Build Coastguard Worker  To fix this problem, use file:// URLs with *three* leading slashes:
1055*6236dae4SAndroid Build Coastguard Worker
1056*6236dae4SAndroid Build Coastguard Worker  file:///D:/blah.txt
1057*6236dae4SAndroid Build Coastguard Worker
1058*6236dae4SAndroid Build Coastguard Worker  Alternatively, if it makes more sense, specify 'localhost' as the host
1059*6236dae4SAndroid Build Coastguard Worker  component:
1060*6236dae4SAndroid Build Coastguard Worker
1061*6236dae4SAndroid Build Coastguard Worker  file://localhost/D:/blah.txt
1062*6236dae4SAndroid Build Coastguard Worker
1063*6236dae4SAndroid Build Coastguard Worker  In either case, curl should now be looking for the correct file.
1064*6236dae4SAndroid Build Coastguard Worker
1065*6236dae4SAndroid Build Coastguard Worker  4.19 Why does not curl return an error when the network cable is unplugged?
1066*6236dae4SAndroid Build Coastguard Worker
1067*6236dae4SAndroid Build Coastguard Worker  Unplugging a cable is not an error situation. The TCP/IP protocol stack
1068*6236dae4SAndroid Build Coastguard Worker  was designed to be fault tolerant, so even though there may be a physical
1069*6236dae4SAndroid Build Coastguard Worker  break somewhere the connection should not be affected, just possibly
1070*6236dae4SAndroid Build Coastguard Worker  delayed. Eventually, the physical break will be fixed or the data will be
1071*6236dae4SAndroid Build Coastguard Worker  re-routed around the physical problem through another path.
1072*6236dae4SAndroid Build Coastguard Worker
1073*6236dae4SAndroid Build Coastguard Worker  In such cases, the TCP/IP stack is responsible for detecting when the
1074*6236dae4SAndroid Build Coastguard Worker  network connection is irrevocably lost. Since with some protocols it is
1075*6236dae4SAndroid Build Coastguard Worker  perfectly legal for the client to wait indefinitely for data, the stack may
1076*6236dae4SAndroid Build Coastguard Worker  never report a problem, and even when it does, it can take up to 20 minutes
1077*6236dae4SAndroid Build Coastguard Worker  for it to detect an issue. The curl option --keepalive-time enables
1078*6236dae4SAndroid Build Coastguard Worker  keep-alive support in the TCP/IP stack which makes it periodically probe the
1079*6236dae4SAndroid Build Coastguard Worker  connection to make sure it is still available to send data. That should
1080*6236dae4SAndroid Build Coastguard Worker  reliably detect any TCP/IP network failure.
1081*6236dae4SAndroid Build Coastguard Worker
1082*6236dae4SAndroid Build Coastguard Worker  TCP keep alive will not detect the network going down before the TCP/IP
1083*6236dae4SAndroid Build Coastguard Worker  connection is established (e.g. during a DNS lookup) or using protocols that
1084*6236dae4SAndroid Build Coastguard Worker  do not use TCP. To handle those situations, curl offers a number of timeouts
1085*6236dae4SAndroid Build Coastguard Worker  on its own. --speed-limit/--speed-time will abort if the data transfer rate
1086*6236dae4SAndroid Build Coastguard Worker  falls too low, and --connect-timeout and --max-time can be used to put an
1087*6236dae4SAndroid Build Coastguard Worker  overall timeout on the connection phase or the entire transfer.
1088*6236dae4SAndroid Build Coastguard Worker
1089*6236dae4SAndroid Build Coastguard Worker  A libcurl-using application running in a known physical environment (e.g.
1090*6236dae4SAndroid Build Coastguard Worker  an embedded device with only a single network connection) may want to act
1091*6236dae4SAndroid Build Coastguard Worker  immediately if its lone network connection goes down. That can be achieved
1092*6236dae4SAndroid Build Coastguard Worker  by having the application monitor the network connection on its own using an
1093*6236dae4SAndroid Build Coastguard Worker  OS-specific mechanism, then signaling libcurl to abort (see also item 5.13).
1094*6236dae4SAndroid Build Coastguard Worker
1095*6236dae4SAndroid Build Coastguard Worker  4.20 curl does not return error for HTTP non-200 responses
1096*6236dae4SAndroid Build Coastguard Worker
1097*6236dae4SAndroid Build Coastguard Worker  Correct. Unless you use -f (--fail).
1098*6236dae4SAndroid Build Coastguard Worker
1099*6236dae4SAndroid Build Coastguard Worker  When doing HTTP transfers, curl will perform exactly what you are asking it
1100*6236dae4SAndroid Build Coastguard Worker  to do and if successful it will not return an error. You can use curl to
1101*6236dae4SAndroid Build Coastguard Worker  test your web server's "file not found" page (that gets 404 back), you can
1102*6236dae4SAndroid Build Coastguard Worker  use it to check your authentication protected webpages (that gets a 401
1103*6236dae4SAndroid Build Coastguard Worker  back) and so on.
1104*6236dae4SAndroid Build Coastguard Worker
1105*6236dae4SAndroid Build Coastguard Worker  The specific HTTP response code does not constitute a problem or error for
1106*6236dae4SAndroid Build Coastguard Worker  curl. It simply sends and delivers HTTP as you asked and if that worked,
1107*6236dae4SAndroid Build Coastguard Worker  everything is fine and dandy. The response code is generally providing more
1108*6236dae4SAndroid Build Coastguard Worker  higher level error information that curl does not care about. The error was
1109*6236dae4SAndroid Build Coastguard Worker  not in the HTTP transfer.
1110*6236dae4SAndroid Build Coastguard Worker
1111*6236dae4SAndroid Build Coastguard Worker  If you want your command line to treat error codes in the 400 and up range
1112*6236dae4SAndroid Build Coastguard Worker  as errors and thus return a non-zero value and possibly show an error
1113*6236dae4SAndroid Build Coastguard Worker  message, curl has a dedicated option for that: -f (CURLOPT_FAILONERROR in
1114*6236dae4SAndroid Build Coastguard Worker  libcurl speak).
1115*6236dae4SAndroid Build Coastguard Worker
1116*6236dae4SAndroid Build Coastguard Worker  You can also use the -w option and the variable %{response_code} to extract
1117*6236dae4SAndroid Build Coastguard Worker  the exact response code that was returned in the response.
1118*6236dae4SAndroid Build Coastguard Worker
1119*6236dae4SAndroid Build Coastguard Worker5. libcurl Issues
1120*6236dae4SAndroid Build Coastguard Worker
1121*6236dae4SAndroid Build Coastguard Worker  5.1 Is libcurl thread-safe?
1122*6236dae4SAndroid Build Coastguard Worker
1123*6236dae4SAndroid Build Coastguard Worker  Yes.
1124*6236dae4SAndroid Build Coastguard Worker
1125*6236dae4SAndroid Build Coastguard Worker  We have written the libcurl code specifically adjusted for multi-threaded
1126*6236dae4SAndroid Build Coastguard Worker  programs. libcurl will use thread-safe functions instead of non-safe ones if
1127*6236dae4SAndroid Build Coastguard Worker  your system has such. Note that you must never share the same handle in
1128*6236dae4SAndroid Build Coastguard Worker  multiple threads.
1129*6236dae4SAndroid Build Coastguard Worker
1130*6236dae4SAndroid Build Coastguard Worker  There may be some exceptions to thread safety depending on how libcurl was
1131*6236dae4SAndroid Build Coastguard Worker  built. Please review the guidelines for thread safety to learn more:
1132*6236dae4SAndroid Build Coastguard Worker  https://curl.se/libcurl/c/threadsafe.html
1133*6236dae4SAndroid Build Coastguard Worker
1134*6236dae4SAndroid Build Coastguard Worker  5.2 How can I receive all data into a large memory chunk?
1135*6236dae4SAndroid Build Coastguard Worker
1136*6236dae4SAndroid Build Coastguard Worker  [ See also the examples/getinmemory.c source ]
1137*6236dae4SAndroid Build Coastguard Worker
1138*6236dae4SAndroid Build Coastguard Worker  You are in full control of the callback function that gets called every time
1139*6236dae4SAndroid Build Coastguard Worker  there is data received from the remote server. You can make that callback do
1140*6236dae4SAndroid Build Coastguard Worker  whatever you want. You do not have to write the received data to a file.
1141*6236dae4SAndroid Build Coastguard Worker
1142*6236dae4SAndroid Build Coastguard Worker  One solution to this problem could be to have a pointer to a struct that you
1143*6236dae4SAndroid Build Coastguard Worker  pass to the callback function. You set the pointer using the
1144*6236dae4SAndroid Build Coastguard Worker  CURLOPT_WRITEDATA option. Then that pointer will be passed to the callback
1145*6236dae4SAndroid Build Coastguard Worker  instead of a FILE * to a file:
1146*6236dae4SAndroid Build Coastguard Worker
1147*6236dae4SAndroid Build Coastguard Worker        /* imaginary struct */
1148*6236dae4SAndroid Build Coastguard Worker        struct MemoryStruct {
1149*6236dae4SAndroid Build Coastguard Worker          char *memory;
1150*6236dae4SAndroid Build Coastguard Worker          size_t size;
1151*6236dae4SAndroid Build Coastguard Worker        };
1152*6236dae4SAndroid Build Coastguard Worker
1153*6236dae4SAndroid Build Coastguard Worker        /* imaginary callback function */
1154*6236dae4SAndroid Build Coastguard Worker        size_t
1155*6236dae4SAndroid Build Coastguard Worker        WriteMemoryCallback(void *ptr, size_t size, size_t nmemb, void *data)
1156*6236dae4SAndroid Build Coastguard Worker        {
1157*6236dae4SAndroid Build Coastguard Worker          size_t realsize = size * nmemb;
1158*6236dae4SAndroid Build Coastguard Worker          struct MemoryStruct *mem = (struct MemoryStruct *)data;
1159*6236dae4SAndroid Build Coastguard Worker
1160*6236dae4SAndroid Build Coastguard Worker          mem->memory = (char *)realloc(mem->memory, mem->size + realsize + 1);
1161*6236dae4SAndroid Build Coastguard Worker          if (mem->memory) {
1162*6236dae4SAndroid Build Coastguard Worker            memcpy(&(mem->memory[mem->size]), ptr, realsize);
1163*6236dae4SAndroid Build Coastguard Worker            mem->size += realsize;
1164*6236dae4SAndroid Build Coastguard Worker            mem->memory[mem->size] = 0;
1165*6236dae4SAndroid Build Coastguard Worker          }
1166*6236dae4SAndroid Build Coastguard Worker          return realsize;
1167*6236dae4SAndroid Build Coastguard Worker        }
1168*6236dae4SAndroid Build Coastguard Worker
1169*6236dae4SAndroid Build Coastguard Worker  5.3 How do I fetch multiple files with libcurl?
1170*6236dae4SAndroid Build Coastguard Worker
1171*6236dae4SAndroid Build Coastguard Worker  libcurl has excellent support for transferring multiple files. You should
1172*6236dae4SAndroid Build Coastguard Worker  just repeatedly set new URLs with curl_easy_setopt() and then transfer it
1173*6236dae4SAndroid Build Coastguard Worker  with curl_easy_perform(). The handle you get from curl_easy_init() is not
1174*6236dae4SAndroid Build Coastguard Worker  only reusable, but you are even encouraged to reuse it if you can, as that
1175*6236dae4SAndroid Build Coastguard Worker  will enable libcurl to use persistent connections.
1176*6236dae4SAndroid Build Coastguard Worker
1177*6236dae4SAndroid Build Coastguard Worker  5.4 Does libcurl do Winsock initialization on Win32 systems?
1178*6236dae4SAndroid Build Coastguard Worker
1179*6236dae4SAndroid Build Coastguard Worker  Yes, if told to in the curl_global_init() call.
1180*6236dae4SAndroid Build Coastguard Worker
1181*6236dae4SAndroid Build Coastguard Worker  5.5 Does CURLOPT_WRITEDATA and CURLOPT_READDATA work on Win32 ?
1182*6236dae4SAndroid Build Coastguard Worker
1183*6236dae4SAndroid Build Coastguard Worker  Yes, but you cannot open a FILE * and pass the pointer to a DLL and have
1184*6236dae4SAndroid Build Coastguard Worker  that DLL use the FILE * (as the DLL and the client application cannot access
1185*6236dae4SAndroid Build Coastguard Worker  each others' variable memory areas). If you set CURLOPT_WRITEDATA you must
1186*6236dae4SAndroid Build Coastguard Worker  also use CURLOPT_WRITEFUNCTION as well to set a function that writes the
1187*6236dae4SAndroid Build Coastguard Worker  file, even if that simply writes the data to the specified FILE *.
1188*6236dae4SAndroid Build Coastguard Worker  Similarly, if you use CURLOPT_READDATA you must also specify
1189*6236dae4SAndroid Build Coastguard Worker  CURLOPT_READFUNCTION.
1190*6236dae4SAndroid Build Coastguard Worker
1191*6236dae4SAndroid Build Coastguard Worker  5.6 What about Keep-Alive or persistent connections?
1192*6236dae4SAndroid Build Coastguard Worker
1193*6236dae4SAndroid Build Coastguard Worker  curl and libcurl have excellent support for persistent connections when
1194*6236dae4SAndroid Build Coastguard Worker  transferring several files from the same server. curl will attempt to reuse
1195*6236dae4SAndroid Build Coastguard Worker  connections for all URLs specified on the same command line/config file, and
1196*6236dae4SAndroid Build Coastguard Worker  libcurl will reuse connections for all transfers that are made using the
1197*6236dae4SAndroid Build Coastguard Worker  same libcurl handle.
1198*6236dae4SAndroid Build Coastguard Worker
1199*6236dae4SAndroid Build Coastguard Worker  When you use the easy interface the connection cache is kept within the easy
1200*6236dae4SAndroid Build Coastguard Worker  handle. If you instead use the multi interface, the connection cache will be
1201*6236dae4SAndroid Build Coastguard Worker  kept within the multi handle and will be shared among all the easy handles
1202*6236dae4SAndroid Build Coastguard Worker  that are used within the same multi handle.
1203*6236dae4SAndroid Build Coastguard Worker
1204*6236dae4SAndroid Build Coastguard Worker  5.7 Link errors when building libcurl on Windows
1205*6236dae4SAndroid Build Coastguard Worker
1206*6236dae4SAndroid Build Coastguard Worker  You need to make sure that your project, and all the libraries (both static
1207*6236dae4SAndroid Build Coastguard Worker  and dynamic) that it links against, are compiled/linked against the same run
1208*6236dae4SAndroid Build Coastguard Worker  time library.
1209*6236dae4SAndroid Build Coastguard Worker
1210*6236dae4SAndroid Build Coastguard Worker  This is determined by the /MD, /ML, /MT (and their corresponding /M?d)
1211*6236dae4SAndroid Build Coastguard Worker  options to the command line compiler. /MD (linking against MSVCRT dll) seems
1212*6236dae4SAndroid Build Coastguard Worker  to be the most commonly used option.
1213*6236dae4SAndroid Build Coastguard Worker
1214*6236dae4SAndroid Build Coastguard Worker  When building an application that uses the static libcurl library, you must
1215*6236dae4SAndroid Build Coastguard Worker  add -DCURL_STATICLIB to your CFLAGS. Otherwise the linker will look for
1216*6236dae4SAndroid Build Coastguard Worker  dynamic import symbols. If you are using Visual Studio, you need to instead
1217*6236dae4SAndroid Build Coastguard Worker  add CURL_STATICLIB in the "Preprocessor Definitions" section.
1218*6236dae4SAndroid Build Coastguard Worker
1219*6236dae4SAndroid Build Coastguard Worker  If you get a linker error like "unknown symbol __imp__curl_easy_init ..." you
1220*6236dae4SAndroid Build Coastguard Worker  have linked against the wrong (static) library. If you want to use the
1221*6236dae4SAndroid Build Coastguard Worker  libcurl.dll and import lib, you do not need any extra CFLAGS, but use one of
1222*6236dae4SAndroid Build Coastguard Worker  the import libraries below. These are the libraries produced by the various
1223*6236dae4SAndroid Build Coastguard Worker  lib/Makefile.* files:
1224*6236dae4SAndroid Build Coastguard Worker
1225*6236dae4SAndroid Build Coastguard Worker       Target:          static lib.   import lib for libcurl*.dll.
1226*6236dae4SAndroid Build Coastguard Worker       -----------------------------------------------------------
1227*6236dae4SAndroid Build Coastguard Worker       MinGW:           libcurl.a     libcurldll.a
1228*6236dae4SAndroid Build Coastguard Worker       MSVC (release):  libcurl.lib   libcurl_imp.lib
1229*6236dae4SAndroid Build Coastguard Worker       MSVC (debug):    libcurld.lib  libcurld_imp.lib
1230*6236dae4SAndroid Build Coastguard Worker       Borland:         libcurl.lib   libcurl_imp.lib
1231*6236dae4SAndroid Build Coastguard Worker
1232*6236dae4SAndroid Build Coastguard Worker  5.8 libcurl.so.X: open failed: No such file or directory
1233*6236dae4SAndroid Build Coastguard Worker
1234*6236dae4SAndroid Build Coastguard Worker  This is an error message you might get when you try to run a program linked
1235*6236dae4SAndroid Build Coastguard Worker  with a shared version of libcurl and your runtime linker (ld.so) could not
1236*6236dae4SAndroid Build Coastguard Worker  find the shared library named libcurl.so.X. (Where X is the number of the
1237*6236dae4SAndroid Build Coastguard Worker  current libcurl ABI, typically 3 or 4).
1238*6236dae4SAndroid Build Coastguard Worker
1239*6236dae4SAndroid Build Coastguard Worker  You need to make sure that ld.so finds libcurl.so.X. You can do that
1240*6236dae4SAndroid Build Coastguard Worker  multiple ways, and it differs somewhat between different operating systems.
1241*6236dae4SAndroid Build Coastguard Worker  They are usually:
1242*6236dae4SAndroid Build Coastguard Worker
1243*6236dae4SAndroid Build Coastguard Worker  * Add an option to the linker command line that specify the hard-coded path
1244*6236dae4SAndroid Build Coastguard Worker    the runtime linker should check for the lib (usually -R)
1245*6236dae4SAndroid Build Coastguard Worker
1246*6236dae4SAndroid Build Coastguard Worker  * Set an environment variable (LD_LIBRARY_PATH for example) where ld.so
1247*6236dae4SAndroid Build Coastguard Worker    should check for libs
1248*6236dae4SAndroid Build Coastguard Worker
1249*6236dae4SAndroid Build Coastguard Worker  * Adjust the system's config to check for libs in the directory where you have
1250*6236dae4SAndroid Build Coastguard Worker    put the library (like Linux's /etc/ld.so.conf)
1251*6236dae4SAndroid Build Coastguard Worker
1252*6236dae4SAndroid Build Coastguard Worker  'man ld.so' and 'man ld' will tell you more details
1253*6236dae4SAndroid Build Coastguard Worker
1254*6236dae4SAndroid Build Coastguard Worker  5.9 How does libcurl resolve hostnames?
1255*6236dae4SAndroid Build Coastguard Worker
1256*6236dae4SAndroid Build Coastguard Worker  libcurl supports a large number of name resolve functions. One of them is
1257*6236dae4SAndroid Build Coastguard Worker  picked at build-time and will be used unconditionally. Thus, if you want to
1258*6236dae4SAndroid Build Coastguard Worker  change name resolver function you must rebuild libcurl and tell it to use a
1259*6236dae4SAndroid Build Coastguard Worker  different function.
1260*6236dae4SAndroid Build Coastguard Worker
1261*6236dae4SAndroid Build Coastguard Worker  - The non-IPv6 resolver that can use one of four different hostname resolve
1262*6236dae4SAndroid Build Coastguard Worker  calls (depending on what your system supports):
1263*6236dae4SAndroid Build Coastguard Worker
1264*6236dae4SAndroid Build Coastguard Worker      A - gethostbyname()
1265*6236dae4SAndroid Build Coastguard Worker      B - gethostbyname_r() with 3 arguments
1266*6236dae4SAndroid Build Coastguard Worker      C - gethostbyname_r() with 5 arguments
1267*6236dae4SAndroid Build Coastguard Worker      D - gethostbyname_r() with 6 arguments
1268*6236dae4SAndroid Build Coastguard Worker
1269*6236dae4SAndroid Build Coastguard Worker  - The IPv6-resolver that uses getaddrinfo()
1270*6236dae4SAndroid Build Coastguard Worker
1271*6236dae4SAndroid Build Coastguard Worker  - The c-ares based name resolver that uses the c-ares library for resolves.
1272*6236dae4SAndroid Build Coastguard Worker    Using this offers asynchronous name resolves.
1273*6236dae4SAndroid Build Coastguard Worker
1274*6236dae4SAndroid Build Coastguard Worker  - The threaded resolver (default option on Windows). It uses:
1275*6236dae4SAndroid Build Coastguard Worker
1276*6236dae4SAndroid Build Coastguard Worker      A - gethostbyname() on plain IPv4 hosts
1277*6236dae4SAndroid Build Coastguard Worker      B - getaddrinfo() on IPv6 enabled hosts
1278*6236dae4SAndroid Build Coastguard Worker
1279*6236dae4SAndroid Build Coastguard Worker  Also note that libcurl never resolves or reverse-lookups addresses given as
1280*6236dae4SAndroid Build Coastguard Worker  pure numbers, such as 127.0.0.1 or ::1.
1281*6236dae4SAndroid Build Coastguard Worker
1282*6236dae4SAndroid Build Coastguard Worker  5.10 How do I prevent libcurl from writing the response to stdout?
1283*6236dae4SAndroid Build Coastguard Worker
1284*6236dae4SAndroid Build Coastguard Worker  libcurl provides a default built-in write function that writes received data
1285*6236dae4SAndroid Build Coastguard Worker  to stdout. Set the CURLOPT_WRITEFUNCTION to receive the data, or possibly
1286*6236dae4SAndroid Build Coastguard Worker  set CURLOPT_WRITEDATA to a different FILE * handle.
1287*6236dae4SAndroid Build Coastguard Worker
1288*6236dae4SAndroid Build Coastguard Worker  5.11 How do I make libcurl not receive the whole HTTP response?
1289*6236dae4SAndroid Build Coastguard Worker
1290*6236dae4SAndroid Build Coastguard Worker  You make the write callback (or progress callback) return an error and
1291*6236dae4SAndroid Build Coastguard Worker  libcurl will then abort the transfer.
1292*6236dae4SAndroid Build Coastguard Worker
1293*6236dae4SAndroid Build Coastguard Worker  5.12 Can I make libcurl fake or hide my real IP address?
1294*6236dae4SAndroid Build Coastguard Worker
1295*6236dae4SAndroid Build Coastguard Worker  No. libcurl operates on a higher level. Besides, faking IP address would
1296*6236dae4SAndroid Build Coastguard Worker  imply sending IP packets with a made-up source address, and then you normally
1297*6236dae4SAndroid Build Coastguard Worker  get a problem with receiving the packet sent back as they would then not be
1298*6236dae4SAndroid Build Coastguard Worker  routed to you.
1299*6236dae4SAndroid Build Coastguard Worker
1300*6236dae4SAndroid Build Coastguard Worker  If you use a proxy to access remote sites, the sites will not see your local
1301*6236dae4SAndroid Build Coastguard Worker  IP address but instead the address of the proxy.
1302*6236dae4SAndroid Build Coastguard Worker
1303*6236dae4SAndroid Build Coastguard Worker  Also note that on many networks NATs or other IP-munging techniques are used
1304*6236dae4SAndroid Build Coastguard Worker  that makes you see and use a different IP address locally than what the
1305*6236dae4SAndroid Build Coastguard Worker  remote server will see you coming from. You may also consider using
1306*6236dae4SAndroid Build Coastguard Worker  https://www.torproject.org/ .
1307*6236dae4SAndroid Build Coastguard Worker
1308*6236dae4SAndroid Build Coastguard Worker  5.13 How do I stop an ongoing transfer?
1309*6236dae4SAndroid Build Coastguard Worker
1310*6236dae4SAndroid Build Coastguard Worker  With the easy interface you make sure to return the correct error code from
1311*6236dae4SAndroid Build Coastguard Worker  one of the callbacks, but none of them are instant. There is no function you
1312*6236dae4SAndroid Build Coastguard Worker  can call from another thread or similar that will stop it immediately.
1313*6236dae4SAndroid Build Coastguard Worker  Instead, you need to make sure that one of the callbacks you use returns an
1314*6236dae4SAndroid Build Coastguard Worker  appropriate value that will stop the transfer. Suitable callbacks that you
1315*6236dae4SAndroid Build Coastguard Worker  can do this with include the progress callback, the read callback and the
1316*6236dae4SAndroid Build Coastguard Worker  write callback.
1317*6236dae4SAndroid Build Coastguard Worker
1318*6236dae4SAndroid Build Coastguard Worker  If you are using the multi interface, you can also stop a transfer by
1319*6236dae4SAndroid Build Coastguard Worker  removing the particular easy handle from the multi stack at any moment you
1320*6236dae4SAndroid Build Coastguard Worker  think the transfer is done or when you wish to abort the transfer.
1321*6236dae4SAndroid Build Coastguard Worker
1322*6236dae4SAndroid Build Coastguard Worker  5.14 Using C++ non-static functions for callbacks?
1323*6236dae4SAndroid Build Coastguard Worker
1324*6236dae4SAndroid Build Coastguard Worker  libcurl is a C library, it does not know anything about C++ member functions.
1325*6236dae4SAndroid Build Coastguard Worker
1326*6236dae4SAndroid Build Coastguard Worker  You can overcome this "limitation" with relative ease using a static
1327*6236dae4SAndroid Build Coastguard Worker  member function that is passed a pointer to the class:
1328*6236dae4SAndroid Build Coastguard Worker
1329*6236dae4SAndroid Build Coastguard Worker     // f is the pointer to your object.
1330*6236dae4SAndroid Build Coastguard Worker     static size_t YourClass::func(void *buffer, size_t sz, size_t n, void *f)
1331*6236dae4SAndroid Build Coastguard Worker     {
1332*6236dae4SAndroid Build Coastguard Worker       // Call non-static member function.
1333*6236dae4SAndroid Build Coastguard Worker       static_cast<YourClass*>(f)->nonStaticFunction();
1334*6236dae4SAndroid Build Coastguard Worker     }
1335*6236dae4SAndroid Build Coastguard Worker
1336*6236dae4SAndroid Build Coastguard Worker     // This is how you pass pointer to the static function:
1337*6236dae4SAndroid Build Coastguard Worker     curl_easy_setopt(hcurl, CURLOPT_WRITEFUNCTION, YourClass::func);
1338*6236dae4SAndroid Build Coastguard Worker     curl_easy_setopt(hcurl, CURLOPT_WRITEDATA, this);
1339*6236dae4SAndroid Build Coastguard Worker
1340*6236dae4SAndroid Build Coastguard Worker  5.15 How do I get an FTP directory listing?
1341*6236dae4SAndroid Build Coastguard Worker
1342*6236dae4SAndroid Build Coastguard Worker  If you end the FTP URL you request with a slash, libcurl will provide you
1343*6236dae4SAndroid Build Coastguard Worker  with a directory listing of that given directory. You can also set
1344*6236dae4SAndroid Build Coastguard Worker  CURLOPT_CUSTOMREQUEST to alter what exact listing command libcurl would use
1345*6236dae4SAndroid Build Coastguard Worker  to list the files.
1346*6236dae4SAndroid Build Coastguard Worker
1347*6236dae4SAndroid Build Coastguard Worker  The follow-up question tends to be how is a program supposed to parse the
1348*6236dae4SAndroid Build Coastguard Worker  directory listing. How does it know what's a file and what's a directory and
1349*6236dae4SAndroid Build Coastguard Worker  what's a symlink etc. If the FTP server supports the MLSD command then it
1350*6236dae4SAndroid Build Coastguard Worker  will return data in a machine-readable format that can be parsed for type.
1351*6236dae4SAndroid Build Coastguard Worker  The types are specified by RFC 3659 section 7.5.1. If MLSD is not supported
1352*6236dae4SAndroid Build Coastguard Worker  then you have to work with what you are given. The LIST output format is
1353*6236dae4SAndroid Build Coastguard Worker  entirely at the server's own liking and the NLST output does not reveal any
1354*6236dae4SAndroid Build Coastguard Worker  types and in many cases does not even include all the directory entries.
1355*6236dae4SAndroid Build Coastguard Worker  Also, both LIST and NLST tend to hide Unix-style hidden files (those that
1356*6236dae4SAndroid Build Coastguard Worker  start with a dot) by default so you need to do "LIST -a" or similar to see
1357*6236dae4SAndroid Build Coastguard Worker  them.
1358*6236dae4SAndroid Build Coastguard Worker
1359*6236dae4SAndroid Build Coastguard Worker  Example - List only directories.
1360*6236dae4SAndroid Build Coastguard Worker  ftp.funet.fi supports MLSD and ftp.kernel.org does not:
1361*6236dae4SAndroid Build Coastguard Worker
1362*6236dae4SAndroid Build Coastguard Worker     curl -s ftp.funet.fi/pub/ -X MLSD | \
1363*6236dae4SAndroid Build Coastguard Worker       perl -lne 'print if s/(?:^|;)type=dir;[^ ]+ (.+)$/$1/'
1364*6236dae4SAndroid Build Coastguard Worker
1365*6236dae4SAndroid Build Coastguard Worker     curl -s ftp.kernel.org/pub/linux/kernel/ | \
1366*6236dae4SAndroid Build Coastguard Worker       perl -lne 'print if s/^d[-rwx]{9}(?: +[^ ]+){7} (.+)$/$1/'
1367*6236dae4SAndroid Build Coastguard Worker
1368*6236dae4SAndroid Build Coastguard Worker  If you need to parse LIST output in libcurl one such existing
1369*6236dae4SAndroid Build Coastguard Worker  list parser is available at https://cr.yp.to/ftpparse.html  Versions of
1370*6236dae4SAndroid Build Coastguard Worker  libcurl since 7.21.0 also provide the ability to specify a wildcard to
1371*6236dae4SAndroid Build Coastguard Worker  download multiple files from one FTP directory.
1372*6236dae4SAndroid Build Coastguard Worker
1373*6236dae4SAndroid Build Coastguard Worker  5.16 I want a different time-out
1374*6236dae4SAndroid Build Coastguard Worker
1375*6236dae4SAndroid Build Coastguard Worker  Sometimes users realize that CURLOPT_TIMEOUT and CURLOPT_CONNECTIMEOUT are
1376*6236dae4SAndroid Build Coastguard Worker  not sufficiently advanced or flexible to cover all the various use cases and
1377*6236dae4SAndroid Build Coastguard Worker  scenarios applications end up with.
1378*6236dae4SAndroid Build Coastguard Worker
1379*6236dae4SAndroid Build Coastguard Worker  libcurl offers many more ways to time-out operations. A common alternative
1380*6236dae4SAndroid Build Coastguard Worker  is to use the CURLOPT_LOW_SPEED_LIMIT and CURLOPT_LOW_SPEED_TIME options to
1381*6236dae4SAndroid Build Coastguard Worker  specify the lowest possible speed to accept before to consider the transfer
1382*6236dae4SAndroid Build Coastguard Worker  timed out.
1383*6236dae4SAndroid Build Coastguard Worker
1384*6236dae4SAndroid Build Coastguard Worker  The most flexible way is by writing your own time-out logic and using
1385*6236dae4SAndroid Build Coastguard Worker  CURLOPT_XFERINFOFUNCTION (perhaps in combination with other callbacks) and
1386*6236dae4SAndroid Build Coastguard Worker  use that to figure out exactly when the right condition is met when the
1387*6236dae4SAndroid Build Coastguard Worker  transfer should get stopped.
1388*6236dae4SAndroid Build Coastguard Worker
1389*6236dae4SAndroid Build Coastguard Worker  5.17 Can I write a server with libcurl?
1390*6236dae4SAndroid Build Coastguard Worker
1391*6236dae4SAndroid Build Coastguard Worker  No. libcurl offers no functions or building blocks to build any kind of
1392*6236dae4SAndroid Build Coastguard Worker  Internet protocol server. libcurl is only a client-side library. For server
1393*6236dae4SAndroid Build Coastguard Worker  libraries, you need to continue your search elsewhere but there exist many
1394*6236dae4SAndroid Build Coastguard Worker  good open source ones out there for most protocols you could want a server
1395*6236dae4SAndroid Build Coastguard Worker  for. There are also really good stand-alone servers that have been tested
1396*6236dae4SAndroid Build Coastguard Worker  and proven for many years. There is no need for you to reinvent them.
1397*6236dae4SAndroid Build Coastguard Worker
1398*6236dae4SAndroid Build Coastguard Worker  5.18 Does libcurl use threads?
1399*6236dae4SAndroid Build Coastguard Worker
1400*6236dae4SAndroid Build Coastguard Worker  Put simply: no, libcurl will execute in the same thread you call it in. All
1401*6236dae4SAndroid Build Coastguard Worker  callbacks will be called in the same thread as the one you call libcurl in.
1402*6236dae4SAndroid Build Coastguard Worker
1403*6236dae4SAndroid Build Coastguard Worker  If you want to avoid your thread to be blocked by the libcurl call, you make
1404*6236dae4SAndroid Build Coastguard Worker  sure you use the non-blocking multi API which will do transfers
1405*6236dae4SAndroid Build Coastguard Worker  asynchronously - still in the same single thread.
1406*6236dae4SAndroid Build Coastguard Worker
1407*6236dae4SAndroid Build Coastguard Worker  libcurl will potentially internally use threads for name resolving, if it
1408*6236dae4SAndroid Build Coastguard Worker  was built to work like that, but in those cases it will create the child
1409*6236dae4SAndroid Build Coastguard Worker  threads by itself and they will only be used and then killed internally by
1410*6236dae4SAndroid Build Coastguard Worker  libcurl and never exposed to the outside.
1411*6236dae4SAndroid Build Coastguard Worker
1412*6236dae4SAndroid Build Coastguard Worker6. License Issues
1413*6236dae4SAndroid Build Coastguard Worker
1414*6236dae4SAndroid Build Coastguard Worker  curl and libcurl are released under a MIT/X derivative license. The license
1415*6236dae4SAndroid Build Coastguard Worker  is liberal and should not impose a problem for your project. This section is
1416*6236dae4SAndroid Build Coastguard Worker  just a brief summary for the cases we get the most questions. (Parts of this
1417*6236dae4SAndroid Build Coastguard Worker  section was much enhanced by Bjorn Reese.)
1418*6236dae4SAndroid Build Coastguard Worker
1419*6236dae4SAndroid Build Coastguard Worker  We are not lawyers and this is not legal advice. You should probably consult
1420*6236dae4SAndroid Build Coastguard Worker  one if you want true and accurate legal insights without our prejudice. Note
1421*6236dae4SAndroid Build Coastguard Worker  especially that this section concerns the libcurl license only; compiling in
1422*6236dae4SAndroid Build Coastguard Worker  features of libcurl that depend on other libraries (e.g. OpenSSL) may affect
1423*6236dae4SAndroid Build Coastguard Worker  the licensing obligations of your application.
1424*6236dae4SAndroid Build Coastguard Worker
1425*6236dae4SAndroid Build Coastguard Worker  6.1 I have a GPL program, can I use the libcurl library?
1426*6236dae4SAndroid Build Coastguard Worker
1427*6236dae4SAndroid Build Coastguard Worker  Yes
1428*6236dae4SAndroid Build Coastguard Worker
1429*6236dae4SAndroid Build Coastguard Worker  Since libcurl may be distributed under the MIT/X derivative license, it can
1430*6236dae4SAndroid Build Coastguard Worker  be used together with GPL in any software.
1431*6236dae4SAndroid Build Coastguard Worker
1432*6236dae4SAndroid Build Coastguard Worker  6.2 I have a closed-source program, can I use the libcurl library?
1433*6236dae4SAndroid Build Coastguard Worker
1434*6236dae4SAndroid Build Coastguard Worker  Yes
1435*6236dae4SAndroid Build Coastguard Worker
1436*6236dae4SAndroid Build Coastguard Worker  libcurl does not put any restrictions on the program that uses the library.
1437*6236dae4SAndroid Build Coastguard Worker
1438*6236dae4SAndroid Build Coastguard Worker  6.3 I have a BSD licensed program, can I use the libcurl library?
1439*6236dae4SAndroid Build Coastguard Worker
1440*6236dae4SAndroid Build Coastguard Worker  Yes
1441*6236dae4SAndroid Build Coastguard Worker
1442*6236dae4SAndroid Build Coastguard Worker  libcurl does not put any restrictions on the program that uses the library.
1443*6236dae4SAndroid Build Coastguard Worker
1444*6236dae4SAndroid Build Coastguard Worker  6.4 I have a program that uses LGPL libraries, can I use libcurl?
1445*6236dae4SAndroid Build Coastguard Worker
1446*6236dae4SAndroid Build Coastguard Worker  Yes
1447*6236dae4SAndroid Build Coastguard Worker
1448*6236dae4SAndroid Build Coastguard Worker  The LGPL license does not clash with other licenses.
1449*6236dae4SAndroid Build Coastguard Worker
1450*6236dae4SAndroid Build Coastguard Worker  6.5 Can I modify curl/libcurl for my program and keep the changes secret?
1451*6236dae4SAndroid Build Coastguard Worker
1452*6236dae4SAndroid Build Coastguard Worker  Yes
1453*6236dae4SAndroid Build Coastguard Worker
1454*6236dae4SAndroid Build Coastguard Worker  The MIT/X derivative license practically allows you to do almost anything
1455*6236dae4SAndroid Build Coastguard Worker  with the sources, on the condition that the copyright texts in the sources
1456*6236dae4SAndroid Build Coastguard Worker  are left intact.
1457*6236dae4SAndroid Build Coastguard Worker
1458*6236dae4SAndroid Build Coastguard Worker  6.6 Can you please change the curl/libcurl license to XXXX?
1459*6236dae4SAndroid Build Coastguard Worker
1460*6236dae4SAndroid Build Coastguard Worker  No.
1461*6236dae4SAndroid Build Coastguard Worker
1462*6236dae4SAndroid Build Coastguard Worker  We have carefully picked this license after years of development and
1463*6236dae4SAndroid Build Coastguard Worker  discussions and a large amount of people have contributed with source code
1464*6236dae4SAndroid Build Coastguard Worker  knowing that this is the license we use. This license puts the restrictions
1465*6236dae4SAndroid Build Coastguard Worker  we want on curl/libcurl and it does not spread to other programs or
1466*6236dae4SAndroid Build Coastguard Worker  libraries that use it. It should be possible for everyone to use libcurl or
1467*6236dae4SAndroid Build Coastguard Worker  curl in their projects, no matter what license they already have in use.
1468*6236dae4SAndroid Build Coastguard Worker
1469*6236dae4SAndroid Build Coastguard Worker  6.7 What are my obligations when using libcurl in my commercial apps?
1470*6236dae4SAndroid Build Coastguard Worker
1471*6236dae4SAndroid Build Coastguard Worker  Next to none. All you need to adhere to is the MIT-style license (stated in
1472*6236dae4SAndroid Build Coastguard Worker  the COPYING file) which basically says you have to include the copyright
1473*6236dae4SAndroid Build Coastguard Worker  notice in "all copies" and that you may not use the copyright holder's name
1474*6236dae4SAndroid Build Coastguard Worker  when promoting your software.
1475*6236dae4SAndroid Build Coastguard Worker
1476*6236dae4SAndroid Build Coastguard Worker  You do not have to release any of your source code.
1477*6236dae4SAndroid Build Coastguard Worker
1478*6236dae4SAndroid Build Coastguard Worker  You do not have to reveal or make public any changes to the libcurl source
1479*6236dae4SAndroid Build Coastguard Worker  code.
1480*6236dae4SAndroid Build Coastguard Worker
1481*6236dae4SAndroid Build Coastguard Worker  You do not have to broadcast to the world that you are using libcurl within
1482*6236dae4SAndroid Build Coastguard Worker  your app.
1483*6236dae4SAndroid Build Coastguard Worker
1484*6236dae4SAndroid Build Coastguard Worker  All we ask is that you disclose "the copyright notice and this permission
1485*6236dae4SAndroid Build Coastguard Worker  notice" somewhere. Most probably like in the documentation or in the section
1486*6236dae4SAndroid Build Coastguard Worker  where other third party dependencies already are mentioned and acknowledged.
1487*6236dae4SAndroid Build Coastguard Worker
1488*6236dae4SAndroid Build Coastguard Worker  As can be seen here: https://curl.se/docs/companies.html and elsewhere,
1489*6236dae4SAndroid Build Coastguard Worker  more and more companies are discovering the power of libcurl and take
1490*6236dae4SAndroid Build Coastguard Worker  advantage of it even in commercial environments.
1491*6236dae4SAndroid Build Coastguard Worker
1492*6236dae4SAndroid Build Coastguard Worker
1493*6236dae4SAndroid Build Coastguard Worker7. PHP/CURL Issues
1494*6236dae4SAndroid Build Coastguard Worker
1495*6236dae4SAndroid Build Coastguard Worker  7.1 What is PHP/CURL?
1496*6236dae4SAndroid Build Coastguard Worker
1497*6236dae4SAndroid Build Coastguard Worker  The module for PHP that makes it possible for PHP programs to access curl-
1498*6236dae4SAndroid Build Coastguard Worker  functions from within PHP.
1499*6236dae4SAndroid Build Coastguard Worker
1500*6236dae4SAndroid Build Coastguard Worker  In the cURL project we call this module PHP/CURL to differentiate it from
1501*6236dae4SAndroid Build Coastguard Worker  curl the command line tool and libcurl the library. The PHP team however
1502*6236dae4SAndroid Build Coastguard Worker  does not refer to it like this (for unknown reasons). They call it plain
1503*6236dae4SAndroid Build Coastguard Worker  CURL (often using all caps) or sometimes ext/curl, but both cause much
1504*6236dae4SAndroid Build Coastguard Worker  confusion to users which in turn gives us a higher question load.
1505*6236dae4SAndroid Build Coastguard Worker
1506*6236dae4SAndroid Build Coastguard Worker  7.2 Who wrote PHP/CURL?
1507*6236dae4SAndroid Build Coastguard Worker
1508*6236dae4SAndroid Build Coastguard Worker  PHP/CURL was initially written by Sterling Hughes.
1509*6236dae4SAndroid Build Coastguard Worker
1510*6236dae4SAndroid Build Coastguard Worker  7.3 Can I perform multiple requests using the same handle?
1511*6236dae4SAndroid Build Coastguard Worker
1512*6236dae4SAndroid Build Coastguard Worker  Yes - at least in PHP version 4.3.8 and later (this has been known to not
1513*6236dae4SAndroid Build Coastguard Worker  work in earlier versions, but the exact version when it started to work is
1514*6236dae4SAndroid Build Coastguard Worker  unknown to me).
1515*6236dae4SAndroid Build Coastguard Worker
1516*6236dae4SAndroid Build Coastguard Worker  After a transfer, you just set new options in the handle and make another
1517*6236dae4SAndroid Build Coastguard Worker  transfer. This will make libcurl reuse the same connection if it can.
1518*6236dae4SAndroid Build Coastguard Worker
1519*6236dae4SAndroid Build Coastguard Worker  7.4 Does PHP/CURL have dependencies?
1520*6236dae4SAndroid Build Coastguard Worker
1521*6236dae4SAndroid Build Coastguard Worker  PHP/CURL is a module that comes with the regular PHP package. It depends on
1522*6236dae4SAndroid Build Coastguard Worker  and uses libcurl, so you need to have libcurl installed properly before
1523*6236dae4SAndroid Build Coastguard Worker  PHP/CURL can be used.
1524*6236dae4SAndroid Build Coastguard Worker
1525*6236dae4SAndroid Build Coastguard Worker8. Development
1526*6236dae4SAndroid Build Coastguard Worker
1527*6236dae4SAndroid Build Coastguard Worker 8.1 Why does curl use C89?
1528*6236dae4SAndroid Build Coastguard Worker
1529*6236dae4SAndroid Build Coastguard Worker As with everything in curl, there is a history and we keep using what we have
1530*6236dae4SAndroid Build Coastguard Worker used before until someone brings up the subject and argues for and works on
1531*6236dae4SAndroid Build Coastguard Worker changing it.
1532*6236dae4SAndroid Build Coastguard Worker
1533*6236dae4SAndroid Build Coastguard Worker We started out using C89 in the 1990s because that was the only way to write
1534*6236dae4SAndroid Build Coastguard Worker a truly portable C program and have it run as widely as possible. C89 was for
1535*6236dae4SAndroid Build Coastguard Worker a long time even necessary to make things work on otherwise considered modern
1536*6236dae4SAndroid Build Coastguard Worker platforms such as Windows. Today, we do not really know how many users that
1537*6236dae4SAndroid Build Coastguard Worker still require the use of a C89 compiler.
1538*6236dae4SAndroid Build Coastguard Worker
1539*6236dae4SAndroid Build Coastguard Worker We will continue to use C89 for as long as nobody brings up a strong enough
1540*6236dae4SAndroid Build Coastguard Worker reason for us to change our minds. The core developers of the project do not
1541*6236dae4SAndroid Build Coastguard Worker feel restricted by this and we are not convinced that going C99 will offer us
1542*6236dae4SAndroid Build Coastguard Worker enough of a benefit to warrant the risk of cutting off a share of users.
1543*6236dae4SAndroid Build Coastguard Worker
1544*6236dae4SAndroid Build Coastguard Worker 8.2 Will curl be rewritten?
1545*6236dae4SAndroid Build Coastguard Worker
1546*6236dae4SAndroid Build Coastguard Worker In one go: no. Little by little over time? Maybe.
1547*6236dae4SAndroid Build Coastguard Worker
1548*6236dae4SAndroid Build Coastguard Worker Over the years, new languages and clever operating environments come and go.
1549*6236dae4SAndroid Build Coastguard Worker Every now and then the urge apparently arises to request that we rewrite curl
1550*6236dae4SAndroid Build Coastguard Worker in another language.
1551*6236dae4SAndroid Build Coastguard Worker
1552*6236dae4SAndroid Build Coastguard Worker Some the most important properties in curl are maintaining the API and ABI
1553*6236dae4SAndroid Build Coastguard Worker for libcurl and keeping the behavior for the command line tool. As long as we
1554*6236dae4SAndroid Build Coastguard Worker can do that, everything else is up for discussion. To maintain the ABI, we
1555*6236dae4SAndroid Build Coastguard Worker probably have to maintain a certain amount of code in C, and to remain rock
1556*6236dae4SAndroid Build Coastguard Worker stable, we will never risk anything by rewriting a lot of things in one go.
1557*6236dae4SAndroid Build Coastguard Worker That said, we can certainly offer more and more optional backends written in
1558*6236dae4SAndroid Build Coastguard Worker other languages, as long as those backends can be plugged in at build-time.
1559*6236dae4SAndroid Build Coastguard Worker Backends can be written in any language, but should probably provide APIs
1560*6236dae4SAndroid Build Coastguard Worker usable from C to ease integration and transition.
1561