luna - curl/docs/FAQ.md

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