diff --git a/SUMMARY.md b/SUMMARY.md index bd92f75585..863d1bceb6 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -2,7 +2,7 @@ * [Introduction](README.md) * [How to read this book](how-to-read.md) -* [The cURL project](project.md) +* [The cURL project](project/README.md) * [How it started](project/started.md) * [The name](project/name.md) * [What does curl do?](project/does.md) @@ -19,19 +19,20 @@ * [The development team](project/devteam.md) * [Users of curl](project/users.md) * [Future](project/future.md) -* [Network and protocols](protocols.md) +* [Network and protocols](protocols/README.md) * [Networking simplified](protocols/network.md) * [Protocols](protocols/protocols.md) * [curl protocols](protocols/curl.md) -* [Install curl](get.md) - * [Linux](get/linux.md) - * [Windows](get/windows.md) - * [MSYS2](get/win-msys2.md) - * [vcpkg](get/win-vcpkg.md) - * [macOS](get/macos.md) - * [Container](get/container.md) -* [Source code](source.md) - * [Open Source](source/opensource.md) + * [HTTP basics](protocols/http.md) +* [Install curl and libcurl](install/README.md) + * [Linux](install/linux.md) + * [Windows](install/windows.md) + * [MSYS2](install/win-msys2.md) + * [vcpkg](install/win-vcpkg.md) + * [macOS](install/macos.md) + * [Container](install/container.md) +* [Source code](source/README.md) + * [Open Source](source/opensource/README.md) * [License](source/opensource/license.md) * [Copyright](source/opensource/copyright.md) * [Code layout](source/layout.md) @@ -40,7 +41,7 @@ * [Contributing](source/contributing.md) * [Reporting vulnerabilities](source/reportvuln.md) * [Website](source/web.md) -* [Build curl](build.md) +* [Build curl and libcurl](build/README.md) * [Autotools](build/autotools.md) * [CMake](build/cmake.md) * [Separate install](build/separate.md) @@ -48,11 +49,11 @@ * [Dependencies](build/deps.md) * [TLS libraries](build/tls.md) * [BoringSSL](build/boringssl.md) -* [Command line basics](cmdline.md) +* [Command line concepts](cmdline/README.md) * [Differences](cmdline/differences.md) * [Command line options](cmdline/options.md) * [Options depend on version](cmdline/versions.md) - * [URLs](cmdline/urls.md) + * [URLs](cmdline/urls/README.md) * [Scheme](cmdline/urls/scheme.md) * [Name and password](cmdline/urls/auth.md) * [Host](cmdline/urls/host.md) @@ -72,13 +73,15 @@ * [Variables](cmdline/variables.md) * [Passwords](cmdline/passwords.md) * [Progress meter](cmdline/progressmeter.md) -* [Using curl](usingcurl.md) - * [Verbose](usingcurl/verbose.md) + * [Version](cmdline/curlver.md) + * [Persistent connections](cmdline/persist.md) + * [Exit code](cmdline/exitcode.md) + * [Copy as curl](cmdline/copyas.md) +* [Command line transfers](usingcurl/README.md) + * [Verbose](usingcurl/verbose/README.md) * [Trace options](usingcurl/verbose/trace.md) * [Write out](usingcurl/verbose/writeout.md) - * [Version](usingcurl/version.md) - * [Persistent connections](usingcurl/persist.md) - * [Downloads](usingcurl/downloads.md) + * [Downloads](usingcurl/downloads/README.md) * [What exactly is downloading?](usingcurl/downloads/whatis.md) * [Storing downloads](usingcurl/downloads/storing.md) * [Download to a file named by the URL](usingcurl/downloads/url-named.md) @@ -94,11 +97,11 @@ * [Retry](usingcurl/downloads/retry.md) * [Resuming and ranges](usingcurl/downloads/resume.md) * [Uploads](usingcurl/uploads.md) - * [Transfer controls](usingcurl/transfers.md) + * [Transfer controls](usingcurl/transfers/README.md) * [Stop slow transfers](usingcurl/transfers/tooslow.md) * [Rate limiting](usingcurl/transfers/rate-limiting.md) * [Request rate limiting](usingcurl/transfers/request-rate.md) - * [Connections](usingcurl/connections.md) + * [Connections](usingcurl/connections/README.md) * [Name resolve tricks](usingcurl/connections/name.md) * [Connection timeout](usingcurl/connections/timeout.md) * [Network interface](usingcurl/connections/interface.md) @@ -106,7 +109,7 @@ * [Keep alive](usingcurl/connections/keepalive.md) * [Timeouts](usingcurl/timeouts.md) * [.netrc](usingcurl/netrc.md) - * [Proxies](usingcurl/proxies.md) + * [Proxies](usingcurl/proxies/README.md) * [Discover your proxy](usingcurl/proxies/discover.md) * [PAC](usingcurl/proxies/pac.md) * [Captive portals](usingcurl/proxies/captive.md) @@ -119,7 +122,6 @@ * [Proxy environment variables](usingcurl/proxies/env.md) * [Proxy headers](usingcurl/proxies/headers.md) * [haproxy](usingcurl/proxies/haproxy.md) - * [Exit status](usingcurl/returns.md) * [TLS](usingcurl/tls.md) * [Ciphers](usingcurl/tls/ciphers.md) * [Enable TLS](usingcurl/tls/enable.md) @@ -139,20 +141,18 @@ * [MQTT](usingcurl/mqtt.md) * [TELNET](usingcurl/telnet.md) * [TFTP](usingcurl/tftp.md) - * [Copy as curl](usingcurl/copyas.md) -* [HTTP with curl](http.md) - * [Protocol basics](http/basics.md) +* [Command line HTTP](http/README.md) * [Method](http/method.md) * [Responses](http/response.md) * [Authentication](http/auth.md) * [Ranges](http/ranges.md) - * [HTTP versions](http/versions.md) + * [HTTP versions](http/versions/README.md) * [HTTP/0.9](http/versions/http09.md) * [HTTP/2](http/versions/http2.md) * [HTTP/3](http/versions/http3.md) * [Conditionals](http/conditionals.md) * [HTTPS](http/https.md) - * [HTTP POST](http/post.md) + * [HTTP POST](http/post/README.md) * [Simple POST](http/post/simple.md) * [Content-Type](http/post/content-type.md) * [Posting binary](http/post/binary.md) @@ -167,7 +167,7 @@ * [Multipart formposts](http/post/multipart.md) * [-d vs -F](http/post/postvspost.md) * [Redirects](http/redirects.md) - * [Modify the HTTP request](http/requests.md) + * [Modify the HTTP request](http/modify/README.md) * [Request method](http/modify/method.md) * [Request target](http/modify/target.md) * [Fragment](http/modify/fragment.md) @@ -175,83 +175,21 @@ * [Referer](http/modify/referer.md) * [User-agent](http/modify/user-agent.md) * [HTTP PUT](http/put.md) - * [Cookies](http/cookies.md) + * [Cookies](http/cookies/README.md) * [Cookie file format](http/cookies/fileformat.md) * [Alternative Services](http/altsvc.md) * [HSTS](http/hsts.md) - * [HTTP cheat sheet](http/cheatsheet.md) * [Scripting browser-like tasks](http/browserlike.md) -* [FTP with curl](ftp.md) +* [Command line FTP](ftp/README.md) * [FTP Directory listing](ftp/dirlist.md) * [Uploading with FTP](ftp/upload.md) * [Custom FTP commands](ftp/cmds.md) * [Two connections](ftp/twoconnections.md) * [Directory traversing](ftp/traversedir.md) * [FTPS](ftp/ftps.md) -* [Using libcurl](libcurl.md) +* [libcurl](libcurl/README.md) * [Header files](libcurl/headers.md) * [Global initialization](libcurl/globalinit.md) - * [Easy handle](libcurl/easyhandle.md) - * [curl easy options](libcurl/options.md) - * [Set numerical options](libcurl/options/num.md) - * [Set string options](libcurl/options/strings.md) - * [TLS options](libcurl/options/tls.md) - * [All options](libcurl/options/all.md) - * [Get option information](libcurl/options/info.md) - * [Drive transfers](libcurl/drive.md) - * [Drive with easy](libcurl/drive/easy.md) - * [Drive with multi](libcurl/drive/multi.md) - * [Drive with multi\_socket](libcurl/drive/multi-socket.md) - * [Callbacks](libcurl/callbacks.md) - * [Write data](libcurl/callbacks/write.md) - * [Read data](libcurl/callbacks/read.md) - * [Progress information](libcurl/callbacks/progress.md) - * [Header data](libcurl/callbacks/header.md) - * [Debug](libcurl/callbacks/debug.md) - * [sockopt](libcurl/callbacks/sockopt.md) - * [SSL context](libcurl/callbacks/sslcontext.md) - * [Seek and ioctl](libcurl/callbacks/seek.md) - * [Network data conversion](libcurl/callbacks/conversions.md) - * [Opensocket and closesocket](libcurl/callbacks/openclosesocket.md) - * [SSH key](libcurl/callbacks/sshkey.md) - * [RTSP interleaved data](libcurl/callbacks/rtsp.md) - * [FTP wildcard matching](libcurl/callbacks/ftpmatch.md) - * [Resolver start](libcurl/callbacks/resolver.md) - * [Sending trailers](libcurl/callbacks/trailers.md) - * [HSTS](libcurl/callbacks/hsts.md) - * [Prereq](libcurl/callbacks/prereq.md) - * [Connection control](libcurl/conn.md) - * [How libcurl connects](libcurl/conn/how.md) - * [Connection reuse](libcurl/conn/reuse.md) - * [Name resolving](libcurl/conn/names.md) - * [Proxies](libcurl/conn/proxies.md) - * [Transfer control](libcurl/control.md) - * [Stop](libcurl/control/stop.md) - * [Stop slow transfers](libcurl/control/stopslow.md) - * [Rate limit](libcurl/control/ratelimit.md) - * [Progress meter](libcurl/control/meter.md) - * [Progress callback](libcurl/control/progress-callback.md) - * [Cleanup](libcurl/cleanup.md) - * [Post transfer info](libcurl/getinfo.md) - * [Share data between handles](libcurl/sharing.md) - * [URL API](libcurl/url.md) - * [Include files](libcurl/url/include.md) - * [Create, cleanup, duplicate](libcurl/url/init.md) - * [Parse a URL](libcurl/url/parse.md) - * [Redirect to a relative URL](libcurl/url/redirect.md) - * [Get a URL](libcurl/url/get.md) - * [Get individual URL parts](libcurl/url/get-part.md) - * [Set individual URL parts](libcurl/url/set-part.md) - * [Append to the query](libcurl/url/append-query.md) - * [CURLOPT\_CURLU](libcurl/url/setopt.md) - * [WebSocket](libcurl/ws.md) - * [Support](libcurl/ws/support.md) - * [URLs](libcurl/ws/urls.md) - * [Concept](libcurl/ws/concept.md) - * [Options](libcurl/ws/options.md) - * [Read](libcurl/ws/read.md) - * [Meta](libcurl/ws/meta.md) - * [Write](libcurl/ws/write.md) * [API compatibility](libcurl/api.md) * [--libcurl](libcurl/--libcurl.md) * [multi-threading](libcurl/threading.md) @@ -259,31 +197,94 @@ * [Verbose operations](libcurl/verbose.md) * [Caches](libcurl/caches.md) * [Performance](libcurl/performance.md) - * [libcurl examples](libcurl/examples.md) - * [Get a simple HTTP page](libcurl/examples/get.md) - * [Get a response into memory](libcurl/examples/getinmem.md) - * [Submit a login form over HTTP](libcurl/examples/login.md) - * [Get an FTP directory listing](libcurl/examples/ftplist.md) - * [Non-blocking HTTP form-post](libcurl/examples/http-ul-nonblock.md) * [for C++ programmers](libcurl/cplusplus.md) -* [HTTP with libcurl](libcurl-http.md) +* [libcurl transfers](transfers/README.md) + * [Easy handle](transfers/easyhandle.md) + * [curl easy options](transfers/options/README.md) + * [Set numerical options](transfers/options/num.md) + * [Set string options](transfers/options/strings.md) + * [TLS options](transfers/options/tls.md) + * [All options](transfers/options/all.md) + * [Get option information](transfers/options/info.md) + * [Drive transfers](transfers/drive/README.md) + * [Drive with easy](transfers/drive/easy.md) + * [Drive with multi](transfers/drive/multi.md) + * [Drive with multi\_socket](transfers/drive/multi-socket.md) + * [Callbacks](transfers/callbacks/README.md) + * [Write data](transfers/callbacks/write.md) + * [Read data](transfers/callbacks/read.md) + * [Progress information](transfers/callbacks/progress.md) + * [Header data](transfers/callbacks/header.md) + * [Debug](transfers/callbacks/debug.md) + * [sockopt](transfers/callbacks/sockopt.md) + * [SSL context](transfers/callbacks/sslcontext.md) + * [Seek and ioctl](transfers/callbacks/seek.md) + * [Network data conversion](transfers/callbacks/conversions.md) + * [Opensocket and closesocket](transfers/callbacks/openclosesocket.md) + * [SSH key](transfers/callbacks/sshkey.md) + * [RTSP interleaved data](transfers/callbacks/rtsp.md) + * [FTP wildcard matching](transfers/callbacks/ftpmatch.md) + * [Resolver start](transfers/callbacks/resolver.md) + * [Sending trailers](transfers/callbacks/trailers.md) + * [HSTS](transfers/callbacks/hsts.md) + * [Prereq](transfers/callbacks/prereq.md) + * [Connection control](transfers/conn/README.md) + * [How libcurl connects](transfers/conn/how.md) + * [Connection reuse](transfers/conn/reuse.md) + * [Name resolving](transfers/conn/names.md) + * [Proxies](transfers/conn/proxies.md) + * [Transfer control](transfers/control/README.md) + * [Stop](transfers/control/stop.md) + * [Stop slow transfers](transfers/control/stopslow.md) + * [Rate limit](transfers/control/ratelimit.md) + * [Progress meter](transfers/control/meter.md) + * [Progress callback](transfers/control/progress-callback.md) + * [Cleanup](transfers/cleanup.md) + * [Post transfer info](transfers/getinfo.md) +* [libcurl HTTP](libcurl-http/README.md) * [Responses](libcurl-http/responses.md) * [Requests](libcurl-http/requests.md) * [Versions](libcurl-http/versions.md) * [Ranges](libcurl-http/ranges.md) * [Authentication](libcurl-http/auth.md) - * [Headers API](libcurl-http/headerapi.md) - * [Header struct](libcurl-http/headerapi/struct.md) - * [Get a header](libcurl-http/headerapi/get.md) - * [Iterate over headers](libcurl-http/headerapi/iterate.md) * [Cookies](libcurl-http/cookies.md) * [Download](libcurl-http/download.md) * [Upload](libcurl-http/upload.md) * [Multiplexing](libcurl-http/multiplexing.md) * [HSTS](libcurl-http/hsts.md) * [alt-svc](libcurl-http/alt-svc.md) -* [Bindings](bindings.md) -* [libcurl internals](internals.md) +* [libcurl helpers](helpers/README.md) + * [Share data between handles](helpers/sharing.md) + * [URL API](helpers/url/README.md) + * [Include files](helpers/url/include.md) + * [Create, cleanup, duplicate](helpers/url/init.md) + * [Parse a URL](helpers/url/parse.md) + * [Redirect to URL](helpers/url/redirect.md) + * [Get a URL](helpers/url/get.md) + * [Get URL parts](helpers/url/get-part.md) + * [Set URL parts](helpers/url/set-part.md) + * [Append to the query](helpers/url/append-query.md) + * [CURLOPT\_CURLU](helpers/url/setopt.md) + * [WebSocket](helpers/ws/README.md) + * [Support](helpers/ws/support.md) + * [URLs](helpers/ws/urls.md) + * [Concept](helpers/ws/concept.md) + * [Options](helpers/ws/options.md) + * [Read](helpers/ws/read.md) + * [Meta](helpers/ws/meta.md) + * [Write](helpers/ws/write.md) + * [Headers API](helpers/headerapi/README.md) + * [Header struct](helpers/headerapi/struct.md) + * [Get a header](helpers/headerapi/get.md) + * [Iterate over headers](helpers/headerapi/iterate.md) +* [libcurl examples](examples/README.md) + * [Get a simple HTTP page](examples/get.md) + * [Get a response into memory](examples/getinmem.md) + * [Submit a login form over HTTP](examples/login.md) + * [Get an FTP directory listing](examples/ftplist.md) + * [Non-blocking HTTP form-post](examples/http-ul-nonblock.md) +* [libcurl bindings](bindings/README.md) +* [libcurl internals](internals/README.md) * [Easy handles and connections](internals/easy.md) * [Everything is multi](internals/multi.md) * [State machines](internals/statemachines.md) @@ -296,7 +297,7 @@ * [Content Encoding](internals/content-encoding.md) * [Structs](internals/structs.md) * [Resolving host names](internals/resolving.md) - * [Tests](internals/tests.md) + * [Tests](internals/tests/README.md) * [Test file format](internals/tests/file-format.md) * [Build tests](internals/tests/build.md) * [Run tests](internals/tests/run.md) diff --git a/bindings.md b/bindings/README.md similarity index 99% rename from bindings.md rename to bindings/README.md index 744533a17b..a703e2ce00 100644 --- a/bindings.md +++ b/bindings/README.md @@ -1,4 +1,4 @@ -# Bindings +# libcurl bindings Creative people have written bindings or interfaces for various environments and programming languages. Using one of these allows you to take advantage of diff --git a/build.md b/build/README.md similarity index 88% rename from build.md rename to build/README.md index a1e1693e8e..f7a390ec9d 100644 --- a/build.md +++ b/build/README.md @@ -1,4 +1,4 @@ -# Build curl +# Build curl and libcurl The source code for this project is written in a way that allows it to get compiled and built on just about any operating system and platform, with as @@ -68,8 +68,8 @@ running `autoreconf -fi` and on Windows, run `buildconf.bat`. ## On Linux and Unix-like systems There are two distinctly different ways to build curl on Linux and other -Unix-like systems; there is the one using [the configure script](build/autotools.md) -and there is [the CMake approach](build/cmake.md). +Unix-like systems; there is the one using [the configure script](autotools.md) +and there is [the CMake approach](cmake.md). There are two different build environments to cater to people's different opinions and tastes. The configure-based build is arguably the more mature and @@ -79,17 +79,17 @@ one. ## On Windows On Windows there are at least four different ways to build. The above -mentioned ways, [the CMake approach](build/cmake.md) and using -[configure](build/autotools.md) with msys work, but the more popular and +mentioned ways, [the CMake approach](cmake.md) and using +[configure](autotools.md) with msys work, but the more popular and common methods are probably building with Microsoft's Visual Studio compiler using either `nmake` or project files. See the build on -[windows](build/windows.md) section. +[windows](windows.md) section. ## Learn more -* [Autotools](build/autotools.md) - build with configure -* [CMake](build/cmake.md) -* [Separate install](build/separate.md) -* [On Windows](build/windows.md) - Windows-specific ways to build -* [Dependencies](build/deps.md) -* [TLS libraries](build/tls.md) +* [Autotools](autotools.md) - build with configure +* [CMake](cmake.md) +* [Separate install](separate.md) +* [On Windows](windows.md) - Windows-specific ways to build +* [Dependencies](deps.md) +* [TLS libraries](tls.md) diff --git a/cmdline.md b/cmdline/README.md similarity index 61% rename from cmdline.md rename to cmdline/README.md index ffd871f8e9..9323862aa3 100644 --- a/cmdline.md +++ b/cmdline/README.md @@ -1,4 +1,4 @@ -# Command line basics +# Command line concepts curl started out as a command-line tool and it has been invoked from shell prompts and from within scripts by countless users over the years. @@ -16,13 +16,17 @@ This is a design choice, as it allows you to really tweak how curl does its protocol communications and you can have curl massage your server implementations in the most creative ways. - * [Differences](cmdline/differences.md) - * [Command line options](cmdline/options.md) - * [Options depend on version](cmdline/versions.md) - * [URLs](cmdline/urls.md) - * [URL globbing](cmdline/globbing.md) - * [List options](cmdline/listopts.md) - * [Config file](cmdline/configfile.md) - * [Variables](cmdline/variables.md) - * [Passwords](cmdline/passwords.md) - * [Progress meter](cmdline/progressmeter.md) + * [Differences](differences.md) + * [Command line options](options.md) + * [Options depend on version](versions.md) + * [URLs](urls/README.md) + * [URL globbing](globbing.md) + * [List options](listopts.md) + * [Config file](configfile.md) + * [Variables](variables.md) + * [Passwords](passwords.md) + * [Progress meter](progressmeter.md) + * [Version](curlver.md) + * [Persistent connections](persist.md) + * [Exit code](exitcode.md) + * [Copy as curl](copyas.md) diff --git a/usingcurl/chrome-copy-as-curl.png b/cmdline/chrome-copy-as-curl.png similarity index 100% rename from usingcurl/chrome-copy-as-curl.png rename to cmdline/chrome-copy-as-curl.png diff --git a/usingcurl/copyas.md b/cmdline/copyas.md similarity index 100% rename from usingcurl/copyas.md rename to cmdline/copyas.md diff --git a/usingcurl/version.md b/cmdline/curlver.md similarity index 100% rename from usingcurl/version.md rename to cmdline/curlver.md diff --git a/usingcurl/returns.md b/cmdline/exitcode.md similarity index 96% rename from usingcurl/returns.md rename to cmdline/exitcode.md index 861e602523..a1c445d84f 100644 --- a/usingcurl/returns.md +++ b/cmdline/exitcode.md @@ -1,4 +1,4 @@ -# Exit status +# Exit code A lot of effort has gone into the project to make curl return a usable exit code when something goes wrong and it always returns 0 (zero) when the @@ -161,9 +161,9 @@ A basic Unix shell script could look like something like this: memory to work with. 28. Operation timeout. The specified time-out period was reached according to - the conditions. curl offers several [timeouts](timeouts.md), and - this exit code tells one of those timeout limits were reached. Extend the - timeout or try changing something else that allows curl to finish its + the conditions. curl offers several [timeouts](../usingcurl/timeouts.md), + and this exit code tells one of those timeout limits were reached. Extend + the timeout or try changing something else that allows curl to finish its operation faster. Often, this happens due to network and remote server situations that you cannot affect locally. @@ -255,8 +255,8 @@ A basic Unix shell script could look like something like this: 51. The server's SSL/TLS certificate or SSH fingerprint failed verification. curl can then not be sure of the server being who it claims to be. See the - [using TLS with curl](tls.md) section for more TLS details and - [using SCP and SFTP with curl](scpsftp.md) for more SSH specific + [using TLS with curl](../usingcurl/tls.md) and + [using SCP and SFTP with curl](../usingcurl/scpsftp.md) sections for more details. 52. The server did not reply anything, which in this context is considered an @@ -411,9 +411,9 @@ circumstances to the exit status number itself so the same error number can get different error messages. Users can also craft their own error messages with -[--write-out](verbose/writeout.md). The pseudo variable `%{onerror}` allows -you to set a message that only gets displayed on errors, and it offers -`%{errormsg}` and `%{exitcode}` among all the variables. +[--write-out](../usingcurl/verbose/writeout.md). The pseudo variable +`%{onerror}` allows you to set a message that only gets displayed on errors, +and it offers `%{errormsg}` and `%{exitcode}` among all the variables. For example: diff --git a/usingcurl/firefox-cliget.png b/cmdline/firefox-cliget.png similarity index 100% rename from usingcurl/firefox-cliget.png rename to cmdline/firefox-cliget.png diff --git a/usingcurl/firefox-copy-as-curl.png b/cmdline/firefox-copy-as-curl.png similarity index 100% rename from usingcurl/firefox-copy-as-curl.png rename to cmdline/firefox-copy-as-curl.png diff --git a/usingcurl/persist.md b/cmdline/persist.md similarity index 100% rename from usingcurl/persist.md rename to cmdline/persist.md diff --git a/usingcurl/safari-copy-as-curl.png b/cmdline/safari-copy-as-curl.png similarity index 100% rename from usingcurl/safari-copy-as-curl.png rename to cmdline/safari-copy-as-curl.png diff --git a/cmdline/urls.md b/cmdline/urls/README.md similarity index 62% rename from cmdline/urls.md rename to cmdline/urls/README.md index 66b2af0804..b341c1818a 100644 --- a/cmdline/urls.md +++ b/cmdline/urls/README.md @@ -13,16 +13,16 @@ Where curl accepts a “URL” as input, it is then really a “URI”. Most of protocols curl understands also have a corresponding URI syntax document that describes how that particular URI format works. -* [Scheme](urls/scheme.md) -* [Name and password](urls/auth.md) -* [Host](urls/host.md) -* [Port number](urls/port.md) -* [Path](urls/path.md) -* [Query](urls/query.md) -* [FTP type](urls/ftptype.md) -* [Fragment](urls/fragment.md) -* [Browsers](urls/browsers.md) -* [Many options and URLs](urls/options.md) -* [Connection reuse](urls/connreuse.md) -* [Parallel transfers](urls/parallel.md) -* [trurl](urls/trurl.md) +* [Scheme](scheme.md) +* [Name and password](auth.md) +* [Host](host.md) +* [Port number](port.md) +* [Path](path.md) +* [Query](query.md) +* [FTP type](ftptype.md) +* [Fragment](fragment.md) +* [Browsers](browsers.md) +* [Many options and URLs](options.md) +* [Connection reuse](connreuse.md) +* [Parallel transfers](parallel.md) +* [trurl](trurl.md) diff --git a/libcurl/examples.md b/examples/README.md similarity index 53% rename from libcurl/examples.md rename to examples/README.md index 60793cbdf0..be214d5efd 100644 --- a/libcurl/examples.md +++ b/examples/README.md @@ -5,8 +5,8 @@ written in C. But since many language bindings for libcurl are thin, they usually expose more or less the same functions and thus they can still be interesting and educational for users of other languages, too. - * [Get a simple HTTP page](examples/get.md) - * [Get a page in memory](examples/getinmem.md) - * [Submit a login form over HTTP](examples/login.md) - * [Get an FTP directory listing](examples/ftplist.md) - * [Non-blocking HTTP form-post](examples/http-ul-nonblock.md) + * [Get a simple HTTP page](get.md) + * [Get a page in memory](getinmem.md) + * [Submit a login form over HTTP](login.md) + * [Get an FTP directory listing](ftplist.md) + * [Non-blocking HTTP form-post](http-ul-nonblock.md) diff --git a/libcurl/examples/ftplist.md b/examples/ftplist.md similarity index 100% rename from libcurl/examples/ftplist.md rename to examples/ftplist.md diff --git a/libcurl/examples/get.md b/examples/get.md similarity index 91% rename from libcurl/examples/get.md rename to examples/get.md index fd7406addb..1c345b8732 100644 --- a/libcurl/examples/get.md +++ b/examples/get.md @@ -8,7 +8,7 @@ protocols as well. Getting the output sent to stdout is a default behavior and usually not what you actually want. Most applications instead install a -[write callback](../callbacks/write.md) to have receive the data that arrives. +[write callback](../transfers/callbacks/write.md) to have receive the data that arrives. #include #include diff --git a/libcurl/examples/getinmem.md b/examples/getinmem.md similarity index 97% rename from libcurl/examples/getinmem.md rename to examples/getinmem.md index 564588a3db..d44187af10 100644 --- a/libcurl/examples/getinmem.md +++ b/examples/getinmem.md @@ -5,7 +5,7 @@ data to stdout (which often is not what you want), this example instead stores the incoming data in a memory buffer that is enlarged as the incoming data grows. -It accomplishes this by using a [write callback](../callbacks/write.md) to +It accomplishes this by using a [write callback](../transfers/callbacks/write.md) to receive the data. This example uses a fixed URL string with a set URL scheme, but you can of diff --git a/libcurl/examples/http-ul-nonblock.md b/examples/http-ul-nonblock.md similarity index 100% rename from libcurl/examples/http-ul-nonblock.md rename to examples/http-ul-nonblock.md diff --git a/libcurl/examples/login.md b/examples/login.md similarity index 100% rename from libcurl/examples/login.md rename to examples/login.md diff --git a/ftp.md b/ftp/README.md similarity index 91% rename from ftp.md rename to ftp/README.md index 5cbfc2b058..d46c1f9a3f 100644 --- a/ftp.md +++ b/ftp/README.md @@ -1,4 +1,4 @@ -# FTP with curl +# Command line FTP FTP, the File Transfer Protocol, is probably the oldest network protocol that curl supports—it was created in the early 1970s. The official spec that @@ -48,3 +48,10 @@ curl either with the `-u, --user` option or embed the info in the URL: curl --user daniel:secret ftp://example.com/download curl ftp://daniel:secret@example.com/download + + * [FTP Directory listing](dirlist.md) + * [Uploading with FTP](upload.md) + * [Custom FTP commands](cmds.md) + * [Two connections](twoconnections.md) + * [Directory traversing](traversedir.md) + * [FTPS](ftps.md) diff --git a/helpers/README.md b/helpers/README.md new file mode 100644 index 0000000000..7fc39000e0 --- /dev/null +++ b/helpers/README.md @@ -0,0 +1,9 @@ +# libcurl helpers + +Doing transfers is good but in order to do *effective* transfers applications +often need some extra API and super-powers. + + * [Share data between handles](sharing.md) + * [URL API](url/README.md) + * [WebSocket](ws/README.md) + * [Headers API](headerapi/README.md) diff --git a/libcurl-http/headerapi.md b/helpers/headerapi/README.md similarity index 94% rename from libcurl-http/headerapi.md rename to helpers/headerapi/README.md index d828d6e7af..d952699112 100644 --- a/libcurl-http/headerapi.md +++ b/helpers/headerapi/README.md @@ -51,6 +51,6 @@ important to remember that the API only returns information about the state of the headers at the exact moment it is called, which might not be the final status if you call it while the transfer is still in progress. - - [Header struct](headerapi/struct.md) - - [Get a header](headerapi/get.md) - - [Iterate of headers](headerapi/iterate.md) + - [Header struct](struct.md) + - [Get a header](get.md) + - [Iterate of headers](iterate.md) diff --git a/libcurl-http/headerapi/get.md b/helpers/headerapi/get.md similarity index 100% rename from libcurl-http/headerapi/get.md rename to helpers/headerapi/get.md diff --git a/libcurl-http/headerapi/iterate.md b/helpers/headerapi/iterate.md similarity index 100% rename from libcurl-http/headerapi/iterate.md rename to helpers/headerapi/iterate.md diff --git a/libcurl-http/headerapi/struct.md b/helpers/headerapi/struct.md similarity index 100% rename from libcurl-http/headerapi/struct.md rename to helpers/headerapi/struct.md diff --git a/libcurl/sharing.md b/helpers/sharing.md similarity index 97% rename from libcurl/sharing.md rename to helpers/sharing.md index 8e30e143b6..1c8e99175a 100644 --- a/libcurl/sharing.md +++ b/helpers/sharing.md @@ -8,7 +8,8 @@ you want. ## Multi handle All easy handles added to the same multi handle automatically share -[connection cache](conn/reuse.md) and [dns cache](conn/names.md). +[connection cache](../transfers/conn/reuse.md) and +[dns cache](../transfers/conn/names.md). ## Sharing between easy handles diff --git a/helpers/url/README.md b/helpers/url/README.md new file mode 100644 index 0000000000..f1d75bda5a --- /dev/null +++ b/helpers/url/README.md @@ -0,0 +1,16 @@ +# URL API + +libcurl offers an API for parsing, updating and generating URLs. Using this, +applications can take advantage of using libcurl's URL parser for its own +purposes. By using the same parser, security problems due to different +interpretations can be avoided. + +* [Include files](include.md) +* [Create, cleanup, duplicate](init.md) +* [Parse a URL](parse.md) +* [Redirect to URL](redirect.md) +* [Get a URL](get.md) +* [Get URL parts](get-part.md) +* [Set URL parts](set-part.md) +* [Append to the query](append-query.md) +* [`CURLOPT_CURLU`](setopt.md) diff --git a/libcurl/url/append-query.md b/helpers/url/append-query.md similarity index 100% rename from libcurl/url/append-query.md rename to helpers/url/append-query.md diff --git a/libcurl/url/get-part.md b/helpers/url/get-part.md similarity index 98% rename from libcurl/url/get-part.md rename to helpers/url/get-part.md index 751d565fbf..6946395318 100644 --- a/libcurl/url/get-part.md +++ b/helpers/url/get-part.md @@ -1,4 +1,4 @@ -# Get individual URL parts +# Get URL parts The `CURLU` handle stores the individual parts of a URL and the application can extract those pieces individually from the handle at any time. If they are diff --git a/libcurl/url/get.md b/helpers/url/get.md similarity index 100% rename from libcurl/url/get.md rename to helpers/url/get.md diff --git a/libcurl/url/include.md b/helpers/url/include.md similarity index 100% rename from libcurl/url/include.md rename to helpers/url/include.md diff --git a/libcurl/url/init.md b/helpers/url/init.md similarity index 100% rename from libcurl/url/init.md rename to helpers/url/init.md diff --git a/libcurl/url/parse.md b/helpers/url/parse.md similarity index 100% rename from libcurl/url/parse.md rename to helpers/url/parse.md diff --git a/libcurl/url/redirect.md b/helpers/url/redirect.md similarity index 92% rename from libcurl/url/redirect.md rename to helpers/url/redirect.md index 2c0a976e1f..8bd3fef10b 100644 --- a/libcurl/url/redirect.md +++ b/helpers/url/redirect.md @@ -1,4 +1,4 @@ -# Redirect to a relative URL +# Redirect to URL When the handle already has parsed a URL, setting a second relative URL makes it "redirect" to adapt to it. diff --git a/libcurl/url/set-part.md b/helpers/url/set-part.md similarity index 98% rename from libcurl/url/set-part.md rename to helpers/url/set-part.md index eee30ebd08..1049d3f31a 100644 --- a/libcurl/url/set-part.md +++ b/helpers/url/set-part.md @@ -1,4 +1,4 @@ -# Set individual URL parts +# Set URL parts The API allows the application to set individual parts of a URL held in the `CURLU` handle, either after having parsed a full URL or instead of parsing diff --git a/libcurl/url/setopt.md b/helpers/url/setopt.md similarity index 100% rename from libcurl/url/setopt.md rename to helpers/url/setopt.md diff --git a/libcurl/ws.md b/helpers/ws/README.md similarity index 74% rename from libcurl/ws.md rename to helpers/ws/README.md index b33f54b471..e171203295 100644 --- a/libcurl/ws.md +++ b/helpers/ws/README.md @@ -9,10 +9,10 @@ A WebSocket client application sets up a connection with an HTTP request that *upgrades* into WebSocket - and once upgraded, the involved parties speak WebSocket over that connection until it is done and the connection is closed. -* [Support](ws/support.md) -* [URLs](ws/urls.md) -* [Concept](ws/concept.md) -* [Options](ws/options.md) -* [Read](ws/read.md) -* [Meta](ws/meta.md) -* [Write](ws/write.md) +* [Support](support.md) +* [URLs](urls.md) +* [Concept](concept.md) +* [Options](options.md) +* [Read](read.md) +* [Meta](meta.md) +* [Write](write.md) diff --git a/libcurl/ws/concept.md b/helpers/ws/concept.md similarity index 82% rename from libcurl/ws/concept.md rename to helpers/ws/concept.md index 73a3d6bd4f..5724aa1228 100644 --- a/libcurl/ws/concept.md +++ b/helpers/ws/concept.md @@ -5,10 +5,10 @@ approaches below. ## 1. The callback approach -It can decide to use the regular [write callback](../callbacks/write.md) to -receive incoming data, and respond to that data in or outside of the callback -with `curl_ws_send`. Thereby treating the entire session as a form of download -from the server. +It can decide to use the regular [write callback](../../transfers/callbacks/write.md) +to receive incoming data, and respond to that data in or outside of the +callback with `curl_ws_send`. Thereby treating the entire session as a form of +download from the server. Within the write callback, an application can call `curl_ws_meta()` to retrieve information about the incoming WebSocket data. diff --git a/libcurl/ws/meta.md b/helpers/ws/meta.md similarity index 100% rename from libcurl/ws/meta.md rename to helpers/ws/meta.md diff --git a/libcurl/ws/options.md b/helpers/ws/options.md similarity index 100% rename from libcurl/ws/options.md rename to helpers/ws/options.md diff --git a/libcurl/ws/read.md b/helpers/ws/read.md similarity index 100% rename from libcurl/ws/read.md rename to helpers/ws/read.md diff --git a/libcurl/ws/support.md b/helpers/ws/support.md similarity index 80% rename from libcurl/ws/support.md rename to helpers/ws/support.md index 99629ec7b0..ea32669f98 100644 --- a/libcurl/ws/support.md +++ b/helpers/ws/support.md @@ -5,6 +5,6 @@ later. Since it is experimental, you need to explicitly enable it in the build for it to be present and available. To figure out if your libcurl installation supports WebSocket, you can call -[`curl_version_info()`](../api.md) and check the `->protocols` fields in the +[`curl_version_info()`](../../libcurl/api.md) and check the `->protocols` fields in the returned struct. It should contain `ws` for it to be present, and probably also `wss`. diff --git a/libcurl/ws/urls.md b/helpers/ws/urls.md similarity index 100% rename from libcurl/ws/urls.md rename to helpers/ws/urls.md diff --git a/libcurl/ws/write.md b/helpers/ws/write.md similarity index 100% rename from libcurl/ws/write.md rename to helpers/ws/write.md diff --git a/how-to-read.md b/how-to-read.md index c2fa80f1db..51cbe6d994 100644 --- a/how-to-read.md +++ b/how-to-read.md @@ -2,61 +2,78 @@ Here is an overview of the main sections of this book and what they cover. -## 1. [The cURL project](project.md) +## 1. [The cURL project](project/README.md) -Project things. How it started, how we work and how often releases are made. +How the project started, how we work and how often releases are made and more. -## 2. [Network and protocols](protocols.md) +## 2. [Network and protocols](protocols/README.md) What exactly are networks and protocols? -## 3. [Install curl](get.md) +## 3. [Install curl and libcurl](install/README.md) How and where to get and install curl. -## 4. [Source code](source.md) +## 4. [Source code](source/README.md) A description of the curl source tree and how the layout of the code is and works. -## 5. [Build curl](build.md) +## 5. [Build curl](build/README.md) How to build curl and libcurl from source. -## 6. [Command line basics](cmdline.md) +## 6. [Command line concepts](cmdline/README.md) Start at the beginning. How do you use curl from a command line? -## 7. [Using curl](usingcurl.md) +## 7. [Command line transfers](usingcurl/README.md) -Going deeper, looking at things you do with curl the command line tool. +Going deeper, looking at how to do and control Internet transfers with the +curl command line tool. -## 8. [HTTP with curl](http.md) +## 8. [Command line HTTP](http/README.md) -Digging deeper on HTTP specific actions to do with the curl command line tool. +Digging deeper on the HTTP specific actions to do with the curl command line +tool. -## 9. [FTP with curl](ftp.md) +## 9. [Command line FTP](ftp/README.md) -Learn FTP specific operations in this chapter. +Learn how to do FTP specific operations with curl in this chapter. -## 10. [Using libcurl](libcurl.md) +## 10. [libcurl](libcurl/README.md) How libcurl works and how you use it when writing your own applications with -it. +it. The fundamentals. -## 11. [HTTP with libcurl](libcurl-http.md) +## 11. [libcurl transfers](transfers/README.md) -A closer look at doing HTTP specific things with libcurl. +How to setup and control libcurl to do Internet transfers using the API. -## 12. [Bindings for libcurl](bindings.md) +## 12. [libcurl HTTP](libcurl-http/README.md) -A casual overview of some of the most popular libcurl bindings and how similar -they are to the libcurl C API. +A closer look at doing and controlling HTTP specific transfers with libcurl. -## 13. [libcurl internals](internals.md) +## 13. [libcurl helpers](helpers/README.md) + +libcurl provides a set of additional APIs, helpers, that go a little beyond +just transfers. These are APIs and and subsystems that can make your libcurl +using application excel. Manage URLs, extract HTTP headers and more. + +## 14. [libcurl examples](examples/README.md) + +Stand-alone libcurl using examples showing off how easy it is to write a first +simple application. + +## 15. [libcurl bindings](bindings/README.md) + +An overview of popular libcurl bindings and how similar they are to the +libcurl C API. + +## 16. [libcurl internals](internals/README.md) Under the hood it works like this… -## 14. [Index](bookindex.md) +## 17. [Index](bookindex.md) The index. diff --git a/http.md b/http.md deleted file mode 100644 index 94dd0b96cc..0000000000 --- a/http.md +++ /dev/null @@ -1,27 +0,0 @@ -# HTTP with curl - -In all user surveys and during all curl's lifetime, HTTP has been the most -important and most frequently used protocol that curl supports. This chapter -explains how to do effective HTTP transfers and general fiddling with curl. - -This mostly works the same way for HTTPS, as they are really the same thing -under the hood, as HTTPS is HTTP with an extra security TLS layer. See also -the specific HTTPS section. - - * [Protocol basics](http/basics.md) - * [Method](http/method.md) - * [Responses](http/response.md) - * [Authentication](http/auth.md) - * [Ranges](http/ranges.md) - * [HTTP versions](http/versions.md) - * [Conditionals](http/conditionals.md) - * [HTTPS](http/https.md) - * [HTTP POST](http/post.md) - * [Redirects](http/redirects.md) - * [Modify the HTTP request](http/requests.md) - * [HTTP PUT](http/put.md) - * [Cookies](http/cookies.md) - * [Alternative Services](http/altsvc.md) - * [HSTS](http/hsts.md) - * [HTTP cheat sheet](http/cheatsheet.md) - * [Scripting browser-like tasks](http/browserlike.md) diff --git a/http/README.md b/http/README.md new file mode 100644 index 0000000000..f17dee0fee --- /dev/null +++ b/http/README.md @@ -0,0 +1,26 @@ +# Command line HTTP + +In all user surveys and during all curl's lifetime, +[HTTP](../protocols/http.md) has been the most important and most frequently +used protocol that curl supports. This chapter explains how to do effective +HTTP transfers and general fiddling with curl. + +This mostly works the same way for HTTPS, as they are really the same thing +under the hood, as HTTPS is HTTP with an extra security TLS layer. See also +the specific HTTPS section. + + * [Method](method.md) + * [Responses](response.md) + * [Authentication](auth.md) + * [Ranges](ranges.md) + * [HTTP versions](versions/README.md) + * [Conditionals](conditionals.md) + * [HTTPS](https.md) + * [HTTP POST](post/README.md) + * [Redirects](redirects.md) + * [Modify the HTTP request](modify/README.md) + * [HTTP PUT](put.md) + * [Cookies](cookies/README.md) + * [Alternative Services](altsvc.md) + * [HSTS](hsts.md) + * [Scripting browser-like tasks](browserlike.md) diff --git a/http/browserlike.md b/http/browserlike.md index 87fe5dd0a6..ad99543ab3 100644 --- a/http/browserlike.md +++ b/http/browserlike.md @@ -23,7 +23,7 @@ The slightly more effective way, that also works even for the cases when the page is shock-full of obfuscated JavaScript, is to run the browser and monitor what HTTP operations it performs. -The [Copy as curl](../usingcurl/copyas.md) section describes how you can +The [Copy as curl](../cmdline/copyas.md) section describes how you can record a browser's request and easily convert that to a curl command line. Those copied curl command lines are often not good enough though since they @@ -37,7 +37,7 @@ A lot of the web today works with a user name and password login prompt somewhere. In many cases you even logged in a while ago with your browser but it has kept the state and keeps you logged in. -The logged-in state is almost always done by using [cookies](cookies.md). +The logged-in state is almost always done by using [cookies](cookies/README.md). A common operation would be to first login and save the returned cookies in a file, and then let the site update the cookies in the subsequent command lines when you traverse the site with curl. @@ -45,8 +45,8 @@ when you traverse the site with curl. ## Web logins and sessions The site at https://example.com/ features a login prompt. The login on the web -site is an HTML form to which you send a [HTTP POST](post.md) to. Save the -response cookies and the response (HTML) output. +site is an HTML form to which you send a [HTTP POST](post/README.md) to. Save +the response cookies and the response (HTML) output. Although the login page is visible (if you would use a browser) on https://example.com/, the HTML form tag on that page informs you about which @@ -89,7 +89,7 @@ You can see that it uses both `-b` for reading cookies from the file and `-c` to store cookies again, for when the server sends back updated cookies. Always, *always*, add `-v` to the command lines when working out the -details. See also the [verbose](../usingcurl/verbose.md) section for more +details. See also the [verbose](../usingcurl/verbose/README.md) section for more details on that. ## Redirects diff --git a/http/cookies.md b/http/cookies/README.md similarity index 99% rename from http/cookies.md rename to http/cookies/README.md index b11361b1b5..39fd2c2c11 100644 --- a/http/cookies.md +++ b/http/cookies/README.md @@ -91,3 +91,5 @@ away. It is the equivalent of closing a browser and starting it up again. Tell curl a new cookie session starts by using `-j, --junk-session-cookies`: curl -j -b cookies.txt http://example.com/ + +* [Cookie file format](fileformat.md) diff --git a/http/method.md b/http/method.md index cc520e0e55..01d21a30d6 100644 --- a/http/method.md +++ b/http/method.md @@ -8,4 +8,4 @@ instead the exact method used depends on the specific options you use. `GET` is default, using `-d` or `-F` makes it a `POST`, `-I` generates a `HEAD` and `-T` sends a `PUT`. -More about this in the [Modify the HTTP request](requests.md) section. +More about this in the [Modify the HTTP request](modify/README.md) section. diff --git a/http/modify/README.md b/http/modify/README.md new file mode 100644 index 0000000000..b4a78dd70f --- /dev/null +++ b/http/modify/README.md @@ -0,0 +1,15 @@ +# Modify the HTTP request + +As described earlier, each HTTP transfer starts with curl sending an HTTP +request. That request consists of a request line and a number of request +headers, and this chapter details how you can modify all of those. + +* [Request method](method.md) +* [Request target](target.md) +* [Fragment](fragment.md) +* [Customize headers](headers.md) +* [Referer](referer.md) +* [User-agent](user-agent.md) + +Of course, changing the [HTTP version](../versions/README.md) is another way to alter +the request. diff --git a/http/post.md b/http/post.md deleted file mode 100644 index 0e78731c57..0000000000 --- a/http/post.md +++ /dev/null @@ -1,20 +0,0 @@ -# HTTP POST - -POST is the HTTP method that was invented to send data to a receiving web -application, and it is how most common HTML forms on the web -work. It usually sends a chunk of relatively small amounts of data to the -receiver. - -* [Simple POST](post/simple.md) -* [Content-Type](post/content-type.md) -* [Posting binary](post/binary.md) -* [JSON](post/json.md) -* [URL encoding](post/url-encode.md) -* [Convert to GET](post/convert-to-get.md) -* [Expect 100-continue](post/expect100.md) -* [Chunked encoded POSTs](post/chunked.md) -* [Hidden form fields](post/hiddenfields.md) -* [Figure out what a browser sends](post/browsersends.md) -* [JavaScript and forms](post/javascript.md) -* [Multipart formposts](post/multipart.md) -* [-d vs -F](post/postvspost.md) diff --git a/http/post/README.md b/http/post/README.md new file mode 100644 index 0000000000..156360b9b1 --- /dev/null +++ b/http/post/README.md @@ -0,0 +1,20 @@ +# HTTP POST + +POST is the HTTP method that was invented to send data to a receiving web +application, and it is how most common HTML forms on the web +work. It usually sends a chunk of relatively small amounts of data to the +receiver. + +* [Simple POST](simple.md) +* [Content-Type](content-type.md) +* [Posting binary](binary.md) +* [JSON](json.md) +* [URL encoding](url-encode.md) +* [Convert to GET](convert-to-get.md) +* [Expect 100-continue](expect100.md) +* [Chunked encoded POSTs](chunked.md) +* [Hidden form fields](hiddenfields.md) +* [Figure out what a browser sends](browsersends.md) +* [JavaScript and forms](javascript.md) +* [Multipart formposts](multipart.md) +* [-d vs -F](postvspost.md) diff --git a/http/post/multipart.md b/http/post/multipart.md index 016b880f38..1304ff5f12 100644 --- a/http/post/multipart.md +++ b/http/post/multipart.md @@ -111,7 +111,7 @@ to submit a multipart form as seen in HTML. 2. Use the development tools in your favorite browser and inspect the POST request in the network tab after you have submitted it. Then convert that HTTP data to a curl command line. Unfortunately, the - [copy as curl](../../usingcurl/copyas.md) feature in the browsers usually do + [copy as curl](../../cmdline/copyas.md) feature in the browsers usually do not actually do multipart formposts particularly well. 3. Inspect the source HTML and convert into a curl command line directly from diff --git a/http/requests.md b/http/requests.md deleted file mode 100644 index 2d1cea3d8d..0000000000 --- a/http/requests.md +++ /dev/null @@ -1,15 +0,0 @@ -# Modify the HTTP request - -As described earlier, each HTTP transfer starts with curl sending an HTTP -request. That request consists of a request line and a number of request -headers, and this chapter details how you can modify all of those. - -* [Request method](modify/method.md) -* [Request target](modify/target.md) -* [Fragment](modify/fragment.md) -* [Customize headers](modify/headers.md) -* [Referer](modify/referer.md) -* [User-agent](modify/user-agent.md) - -Of course, changing the [HTTP version](versions.md) is another way to alter -the request. diff --git a/http/versions.md b/http/versions/README.md similarity index 92% rename from http/versions.md rename to http/versions/README.md index 18c7404b04..359e7a5754 100644 --- a/http/versions.md +++ b/http/versions/README.md @@ -22,6 +22,6 @@ Non-HTTP/2 capable curls get 1.1 over HTTPS by default. | --http2-prior-knowledge | HTTP/2 | --http3 | HTTP/3 -* [HTTP/0.9](versions/http09.md) -* [HTTP/2](versions/http2.md) -* [HTTP/3](versions/http3.md) +* [HTTP/0.9](http09.md) +* [HTTP/2](http2.md) +* [HTTP/3](http3.md) diff --git a/get.md b/install/README.md similarity index 68% rename from get.md rename to install/README.md index 68381434f2..5247d6a76f 100644 --- a/get.md +++ b/install/README.md @@ -1,4 +1,4 @@ -# Install curl +# Install curl and libcurl curl is totally free, open and available. There are numerous ways to get it and install it for most operating systems and architecture. This section gives @@ -10,7 +10,9 @@ In addition, You can always download the source from [curl.se](https://curl.se) or find binary packages to download from there. - * [Linux](get/linux.md) - * [Windows](get/windows.md) - * [macOS](get/macos.md) - * [Container](get/container.md) +Commonly, libcurl is installed at the same time as curl. + + * [Linux](linux.md) + * [Windows](windows.md) + * [macOS](macos.md) + * [Container](container.md) diff --git a/get/container.md b/install/container.md similarity index 100% rename from get/container.md rename to install/container.md diff --git a/get/linux.md b/install/linux.md similarity index 100% rename from get/linux.md rename to install/linux.md diff --git a/get/macos.md b/install/macos.md similarity index 100% rename from get/macos.md rename to install/macos.md diff --git a/get/win-msys2.md b/install/win-msys2.md similarity index 100% rename from get/win-msys2.md rename to install/win-msys2.md diff --git a/get/win-vcpkg.md b/install/win-vcpkg.md similarity index 100% rename from get/win-vcpkg.md rename to install/win-vcpkg.md diff --git a/get/windows.md b/install/windows.md similarity index 100% rename from get/windows.md rename to install/windows.md diff --git a/internals.md b/internals.md deleted file mode 100644 index 008550b7e4..0000000000 --- a/internals.md +++ /dev/null @@ -1,24 +0,0 @@ -# libcurl internals - -libcurl is never finished and is not just an off-the-shelf product. It is a -living project that is improved and modified on almost a daily basis. We -depend on skilled and interested hackers to fix bugs and to add features. - -This chapter is meant to describe internal details to aid keen libcurl hackers -to learn some basic concepts on how libcurl works internally and thus possibly -where to look for problems or where to add things when you want to make the -library do something new. - - * [Easy handles and connections](internals/easy.md) - * [Everything is multi](internals/multi.md) - * [State machines](internals/statemachines.md) - * [Protocol handler](internals/handler.md) - * [Backends](internals/backends.md) - * [Caches and state](internals/caches.md) - * [Timeouts](internals/timeouts.md) - * [Windows vs Unix](internals/windows-vs-unix.md) - * [Memory debugging](internals/memory-debugging.md) - * [Content Encoding](internals/content-encoding.md) - * [Structs](internals/structs.md) - * [Resolving host names](internals/resolving.md) - * [Tests](internals/tests.md) diff --git a/internals/README.md b/internals/README.md new file mode 100644 index 0000000000..dce1266aa8 --- /dev/null +++ b/internals/README.md @@ -0,0 +1,24 @@ +# libcurl internals + +libcurl is never finished and is not just an off-the-shelf product. It is a +living project that is improved and modified on almost a daily basis. We +depend on skilled and interested hackers to fix bugs and to add features. + +This chapter is meant to describe internal details to aid keen libcurl hackers +to learn some basic concepts on how libcurl works internally and thus possibly +where to look for problems or where to add things when you want to make the +library do something new. + + * [Easy handles and connections](easy.md) + * [Everything is multi](multi.md) + * [State machines](statemachines.md) + * [Protocol handler](handler.md) + * [Backends](backends.md) + * [Caches and state](caches.md) + * [Timeouts](timeouts.md) + * [Windows vs Unix](windows-vs-unix.md) + * [Memory debugging](memory-debugging.md) + * [Content Encoding](content-encoding.md) + * [Structs](structs.md) + * [Resolving host names](resolving.md) + * [Tests](tests/README.md) diff --git a/internals/tests.md b/internals/tests/README.md similarity index 60% rename from internals/tests.md rename to internals/tests/README.md index 67a0e577a1..f9fc202c0b 100644 --- a/internals/tests.md +++ b/internals/tests/README.md @@ -14,15 +14,15 @@ does not rely on any third party test frameworks. The tests are meant to be possible to build and run on virtually all platforms available. -* [Test file format](tests/file-format.md) -* [Build tests](tests/build.md) -* [Run tests](tests/run.md) -* [Debug builds](tests/debug.md) -* [Test servers](tests/servers.md) -* [curl tests](tests/curl.md) -* [libcurl tests](tests/libcurl.md) -* [Unit tests](tests/unit.md) -* [Valgrind](tests/valgrind.md) -* [Continuous Integration](tests/ci.md) -* [Autobuilds](tests/autobuilds.md) -* [Torture](tests/torture.md) +* [Test file format](file-format.md) +* [Build tests](build.md) +* [Run tests](run.md) +* [Debug builds](debug.md) +* [Test servers](servers.md) +* [curl tests](curl.md) +* [libcurl tests](libcurl.md) +* [Unit tests](unit.md) +* [Valgrind](valgrind.md) +* [Continuous Integration](ci.md) +* [Autobuilds](autobuilds.md) +* [Torture](torture.md) diff --git a/libcurl-http.md b/libcurl-http.md deleted file mode 100644 index 642f84a017..0000000000 --- a/libcurl-http.md +++ /dev/null @@ -1,33 +0,0 @@ -# HTTP with libcurl - -HTTP is by far the most commonly used protocol by libcurl users and libcurl -offers countless ways of modifying such transfers. See the -[HTTP protocol basics](http/basics.md) for some basics on how the HTTP protocol -works. - -## HTTPS - -Doing HTTPS is typically done the same way as for HTTP as the extra security -layer and server verification etc is done automatically and transparently by -default. Just use the `https://` scheme in the URL. - -HTTPS is HTTP with TLS on top. See also the [TLS options](libcurl/options/tls.md) -section. - -## HTTP proxy - -See [using Proxies with libcurl](libcurl/conn/proxies.md) - -## Sections - - * [HTTP responses](libcurl-http/responses.md) - * [HTTP requests](libcurl-http/requests.md) - * [HTTP versions](libcurl-http/versions.md) - * [HTTP ranges](libcurl-http/ranges.md) - * [HTTP authentication](libcurl-http/auth.md) - * [Cookies with libcurl](libcurl-http/cookies.md) - * [Download](libcurl-http/download.md) - * [Upload](libcurl-http/upload.md) - * [Multiplexing](libcurl-http/multiplexing.md) - * [HSTS](libcurl-http/hsts.md) - * [alt-svc](libcurl-http/alt-svc.md) diff --git a/libcurl-http/README.md b/libcurl-http/README.md new file mode 100644 index 0000000000..68af02447b --- /dev/null +++ b/libcurl-http/README.md @@ -0,0 +1,33 @@ +# libcurl HTTP + +HTTP is by far the most commonly used protocol by libcurl users and libcurl +offers countless ways of modifying such transfers. See the +[HTTP protocol basics](../protocols/http.md) for some basics on how the HTTP protocol +works. + +## HTTPS + +Doing HTTPS is typically done the same way as for HTTP as the extra security +layer and server verification etc is done automatically and transparently by +default. Just use the `https://` scheme in the URL. + +HTTPS is HTTP with TLS on top. See also the +[TLS transfer options](../transfers/options/tls.md) section. + +## HTTP proxy + +See [using Proxies with libcurl](../transfers/conn/proxies.md) + +## Sections + + * [HTTP responses](responses.md) + * [HTTP requests](requests.md) + * [HTTP versions](versions.md) + * [HTTP ranges](ranges.md) + * [HTTP authentication](auth.md) + * [Cookies with libcurl](cookies.md) + * [Download](download.md) + * [Upload](upload.md) + * [Multiplexing](multiplexing.md) + * [HSTS](hsts.md) + * [alt-svc](alt-svc.md) diff --git a/libcurl-http/download.md b/libcurl-http/download.md index ba20bd7aa7..afd930fa2f 100644 --- a/libcurl-http/download.md +++ b/libcurl-http/download.md @@ -31,8 +31,8 @@ body is, by using `CURLOPT_HEADER`: curl_easy_perform(easy); Or you can opt to store the headers in a separate download file, by relying on -the default behaviors of the [write](../libcurl/callbacks/write.md) and -[header callbacks](../libcurl/callbacks/header.md): +the default behaviors of the [write](../transfers/callbacks/write.md) and +[header callbacks](../transfers/callbacks/header.md): easy = curl_easy_init(); FILE *file = fopen("headers", "wb"); diff --git a/libcurl-http/responses.md b/libcurl-http/responses.md index f1363fefcf..48d79e295c 100644 --- a/libcurl-http/responses.md +++ b/libcurl-http/responses.md @@ -6,8 +6,8 @@ and thus nonexistent. An HTTP response however always has response headers. ## Response body -The response body is passed to the [write callback](../libcurl/callbacks/write.md) -and the response headers to the [header callback](../libcurl/callbacks/header.md). +The response body is passed to the [write callback](../transfers/callbacks/write.md) +and the response headers to the [header callback](../transfers/callbacks/header.md). Virtually all libcurl-using applications need to set at least one of those callbacks instructing libcurl what to do with received headers and data. diff --git a/libcurl-http/upload.md b/libcurl-http/upload.md index 8d2f03abe3..043acbee4a 100644 --- a/libcurl-http/upload.md +++ b/libcurl-http/upload.md @@ -18,7 +18,7 @@ server. With libcurl you normally provide that data as a pointer and a length: curl_easy_setopt(easy, CURLOPT_POSTFIELDSIZE, (long)datalength); Or you tell libcurl that it is a post but would prefer to have libcurl instead -get the data by using the regular [read callback](../libcurl/callbacks/read.md): +get the data by using the regular [read callback](../transfers/callbacks/read.md): curl_easy_setopt(easy, CURLOPT_POST, 1L); curl_easy_setopt(easy, CURLOPT_READFUNCTION, read_callback); diff --git a/libcurl.md b/libcurl/README.md similarity index 74% rename from libcurl.md rename to libcurl/README.md index dc3d53bb40..47f23f9633 100644 --- a/libcurl.md +++ b/libcurl/README.md @@ -1,4 +1,4 @@ -# Using libcurl +# libcurl The engine in the curl command-line tool is libcurl. libcurl is also the engine in thousands of tools, services and applications out there today, @@ -8,10 +8,10 @@ performing their Internet data transfers. libcurl is a library of functions that are provided with a C API, for applications written in C. You can easily use it from C++ too, with only a few -considerations (see [libcurl for C++ programmers](libcurl/cplusplus.md)). For -other languages, there exist *bindings* that work as intermediate layers -between libcurl the library and corresponding functions for the particular -language you like. +considerations (see [libcurl for C++ programmers](cplusplus.md)). For other +languages, there exist *bindings* that work as intermediate layers between +libcurl the library and corresponding functions for the particular language +you like. ## Transfer oriented @@ -40,3 +40,14 @@ does once you tell it. This makes libcurl's behaviors easier to guess and depend on, and also it makes it easier to maintain old behavior and add new features. Only applications that actually ask for and use the new features get that behavior. + + * [Header files](headers.md) + * [Global initialization](globalinit.md) + * [API compatibility](api.md) + * [--libcurl](--libcurl.md) + * [multi-threading](threading.md) + * [CURLcode return codes](curlcode.md) + * [Verbose operations](verbose.md) + * [Caches](caches.md) + * [Performance](performance.md) + * [for C++ programmers](cplusplus.md) diff --git a/libcurl/caches.md b/libcurl/caches.md index 8ea005dcd0..0137dcb2aa 100644 --- a/libcurl/caches.md +++ b/libcurl/caches.md @@ -9,7 +9,7 @@ the easy handles that are added to that single multi handle, and when the easy interface is used they are kept within that handle. You can instruct libcurl to share some of the caches with the -[share interface](sharing.md). +[share interface](../helpers/sharing.md). ## DNS cache diff --git a/libcurl/control.md b/libcurl/control.md deleted file mode 100644 index e315a8f3af..0000000000 --- a/libcurl/control.md +++ /dev/null @@ -1,10 +0,0 @@ -# Transfer control - -An ongoing transfer can be controlled in several ways. The following pages -describe further details: - -* [Stop](control/stop.md) -* [Stop slow transfers](control/stopslow.md) -* [Rate limit](control/ratelimit.md) -* [Progress meter](control/meter.md) -* [Progress callback](control/progress-callback.md) diff --git a/libcurl/performance.md b/libcurl/performance.md index 616dbba837..851a4dd537 100644 --- a/libcurl/performance.md +++ b/libcurl/performance.md @@ -48,7 +48,7 @@ Avoid doing complicated logic or use locks/mutexes in your libcurl callbacks. If you use multiple easy handles, you can still share data and caches between them in order to increase performance. Take a closer look at -[the share API](sharing.md). +[the share API](../helpers/sharing.md). ## threads diff --git a/libcurl/url.md b/libcurl/url.md deleted file mode 100644 index 909847c719..0000000000 --- a/libcurl/url.md +++ /dev/null @@ -1,16 +0,0 @@ -# URL API - -libcurl offers an API for parsing, updating and generating URLs. Using this, -applications can take advantage of using libcurl's URL parser for its own -purposes. By using the same parser, security problems due to different -interpretations can be avoided. - -* [Include files](url/include.md) -* [Create, cleanup, duplicate](url/init.md) -* [Parse a URL](url/parse.md) -* [Redirect to a relative URL](url/redirect.md) -* [Get a URL](url/get.md) -* [Get individual URL parts](url/get-part.md) -* [Set individual URL parts](url/set-part.md) -* [Append to the query](url/append-query.md) -* [`CURLOPT_CURLU`](url/setopt.md) diff --git a/project.md b/project.md deleted file mode 100644 index 02b10a5250..0000000000 --- a/project.md +++ /dev/null @@ -1,9 +0,0 @@ -# The cURL project - -![curl logo](curl-logo.jpg) - -A funny detail about Open Source projects is that they are called *projects*, -as if they were somehow limited in time or ever can get done. The cURL project -is a number of loosely coupled individual volunteers working on writing -software together with a common mission: to do reliable data transfers with -Internet protocols, as Open Source. diff --git a/project/README.md b/project/README.md new file mode 100644 index 0000000000..70376d2e47 --- /dev/null +++ b/project/README.md @@ -0,0 +1,26 @@ +# The cURL project + +![curl logo](curl-logo.jpg) + +A funny detail about Open Source projects is that they are called *projects*, +as if they were somehow limited in time or ever can get done. The cURL project +is a number of loosely coupled individual volunteers working on writing +software together with a common mission: to do reliable data transfers with +Internet protocols, as Open Source. + + * [How it started](started.md) + * [The name](name.md) + * [What does curl do?](does.md) + * [Project communication](comm.md) + * [Mailing list etiquette](etiquette.md) + * [Mailing lists](maillists.md) + * [Reporting bugs](bugs.md) + * [Commercial support](support.md) + * [Releases](releases.md) + * [Security](security.md) + * [Trust](trust.md) + * [Code of Conduct](coc.md) + * [Development](devel.md) + * [The development team](devteam.md) + * [Users of curl](users.md) + * [Future](future.md) diff --git a/curl-logo.jpg b/project/curl-logo.jpg similarity index 100% rename from curl-logo.jpg rename to project/curl-logo.jpg diff --git a/project/does.md b/project/does.md index 6e2e13f55d..656feae5b8 100644 --- a/project/does.md +++ b/project/does.md @@ -58,4 +58,5 @@ architecture and for any purpose. libcurl is also extremely liberally licensed to avoid that becoming an obstacle. libcurl is written in traditional and conservative C. Where other languages -are preferred, people have created libcurl [bindings](../bindings.md) for them. +are preferred, people have created libcurl [bindings](../bindings/README.md) +for them. diff --git a/protocols.md b/protocols.md deleted file mode 100644 index f6fd6c0c5a..0000000000 --- a/protocols.md +++ /dev/null @@ -1,10 +0,0 @@ -# Network and protocols - -Before diving in and talking about how to use curl to get things done, let's -take a look at what all this networking is and how it works, using -simplifications and some minor shortcuts to give an easy overview. - -The basics are in the [networking simplified](protocols/network.md) chapter -that tries to just draw a simple picture of what networking is from a curl -perspective, and the [protocols](protocols/protocols.md) section which -explains what exactly a "protocol" is and how that works. diff --git a/protocols/README.md b/protocols/README.md new file mode 100644 index 0000000000..1a9738da20 --- /dev/null +++ b/protocols/README.md @@ -0,0 +1,15 @@ +# Network and protocols + +Before diving in and talking about how to use curl to get things done, let's +take a look at what all this networking is and how it works, using +simplifications and some minor shortcuts to give an easy overview. + +The basics are in the [networking simplified](network.md) chapter that tries +to just draw a simple picture of what networking is from a curl perspective, +and the [protocols](protocols.md) section which explains what exactly a +"protocol" is and how that works. + + * [Networking simplified](network.md) + * [Protocols](protocols.md) + * [curl protocols](curl.md) + * [HTTP basics](http.md) diff --git a/http/basics.md b/protocols/http.md similarity index 93% rename from http/basics.md rename to protocols/http.md index 19536314f6..75b1e805a4 100644 --- a/http/basics.md +++ b/protocols/http.md @@ -1,8 +1,5 @@ -# Protocol basics +# HTTP basics -(This assumes you have read the [Network and protocols](../protocols.md) -section or are otherwise already familiar with protocols.) - HTTP is a protocol that is easy to learn the basics of. A client connects to a server—and it is always the client that takes the initiative—sends a request and receives a response. Both the request and the response consist of diff --git a/source.md b/source/README.md similarity index 78% rename from source.md rename to source/README.md index 0cf79e62c0..7538f0cf5f 100644 --- a/source.md +++ b/source/README.md @@ -23,3 +23,11 @@ repository](https://github.com/curl/curl/). This gets the latest curl code downloaded and unpacked in a directory on your local system. + + * [Open Source](opensource/README.md) + * [Code layout](layout.md) + * [Handling build options](options.md) + * [Code style](style.md) + * [Contributing](contributing.md) + * [Reporting vulnerabilities](reportvuln.md) + * [Website](web.md) diff --git a/source/layout.md b/source/layout.md index c791d4533a..c96d78c3c9 100644 --- a/source/layout.md +++ b/source/layout.md @@ -164,7 +164,7 @@ different libcurl functions. Contains around 100 stand-alone examples that are meant to help readers understand how libcurl can be used. -See also the [libcurl examples](../libcurl/examples.md) section of this book. +See also the [libcurl examples](../examples/README.md) section of this book. ## scripts diff --git a/source/opensource.md b/source/opensource/README.md similarity index 90% rename from source/opensource.md rename to source/opensource/README.md index 5adb0fce48..3389bbedd3 100644 --- a/source/opensource.md +++ b/source/opensource/README.md @@ -10,3 +10,6 @@ comply with the definition. Free Software is an older and related term that mostly says the same thing for all our intents and purposes, but we stick to the term Open Source in this document for simplicity. + +* [License](license.md) +* [Copyright](copyright.md) diff --git a/spellcheck.yaml b/spellcheck.yaml index c522c82f0d..cb78e548c7 100644 --- a/spellcheck.yaml +++ b/spellcheck.yaml @@ -24,4 +24,4 @@ matrix: - 'code' - 'pre' sources: - - '**/*.md|!README.md|!SUMMARY.md|!bindings.md|!bookindex.md|!libcurl/options/all.md|!build/deps.md' + - '**/*.md|!README.md|!SUMMARY.md|!bindings/README.md|!bookindex.md|!transfers/options/all.md|!build/deps.md' diff --git a/transfers/README.md b/transfers/README.md new file mode 100644 index 0000000000..3e6aeb4fd2 --- /dev/null +++ b/transfers/README.md @@ -0,0 +1,13 @@ +# libcurl transfers + +In this chapter we go through the steps on how to make Internet transfers with +libcurl. The core function. + + * [Easy handle](easyhandle.md) + * [curl easy options](options/README.md) + * [Drive transfers](drive/README.md) + * [Callbacks](callbacks/README.md) + * [Connection control](conn/README.md) + * [Transfer control](control/README.md) + * [Cleanup](cleanup.md) + * [Post transfer info](getinfo.md) diff --git a/libcurl/callbacks.md b/transfers/callbacks/README.md similarity index 57% rename from libcurl/callbacks.md rename to transfers/callbacks/README.md index b8bc6ff416..454939e61d 100644 --- a/libcurl/callbacks.md +++ b/transfers/callbacks/README.md @@ -18,20 +18,20 @@ callback function. Unless explicitly stated in a libcurl function documentation, it is not legal to invoke libcurl functions from within a libcurl callback. - * [Write data](callbacks/write.md) - * [Read data](callbacks/read.md) - * [Progress information](callbacks/progress.md) - * [Header data](callbacks/header.md) - * [Debug](callbacks/debug.md) - * [sockopt](callbacks/sockopt.md) - * [SSL context](callbacks/sslcontext.md) - * [Seek and ioctl](callbacks/seek.md) - * [Network data conversion](callbacks/conversions.md) - * [Opensocket and closesocket](callbacks/openclosesocket.md) - * [SSH key](callbacks/sshkey.md) - * [RTSP interleaved data](callbacks/rtsp.md) - * [FTP wildcard matching](callbacks/ftpmatch.md) - * [Resolver start](callbacks/resolver.md) - * [Sending trailers](callbacks/trailers.md) - * [HSTS](callbacks/hsts.md) - * [Prereq](callbacks/prereq.md) + * [Write data](write.md) + * [Read data](read.md) + * [Progress information](progress.md) + * [Header data](header.md) + * [Debug](debug.md) + * [sockopt](sockopt.md) + * [SSL context](sslcontext.md) + * [Seek and ioctl](seek.md) + * [Network data conversion](conversions.md) + * [Opensocket and closesocket](openclosesocket.md) + * [SSH key](sshkey.md) + * [RTSP interleaved data](rtsp.md) + * [FTP wildcard matching](ftpmatch.md) + * [Resolver start](resolver.md) + * [Sending trailers](trailers.md) + * [HSTS](hsts.md) + * [Prereq](prereq.md) diff --git a/libcurl/callbacks/conversions.md b/transfers/callbacks/conversions.md similarity index 100% rename from libcurl/callbacks/conversions.md rename to transfers/callbacks/conversions.md diff --git a/libcurl/callbacks/debug.md b/transfers/callbacks/debug.md similarity index 100% rename from libcurl/callbacks/debug.md rename to transfers/callbacks/debug.md diff --git a/libcurl/callbacks/ftpmatch.md b/transfers/callbacks/ftpmatch.md similarity index 100% rename from libcurl/callbacks/ftpmatch.md rename to transfers/callbacks/ftpmatch.md diff --git a/libcurl/callbacks/header.md b/transfers/callbacks/header.md similarity index 100% rename from libcurl/callbacks/header.md rename to transfers/callbacks/header.md diff --git a/libcurl/callbacks/hsts.md b/transfers/callbacks/hsts.md similarity index 100% rename from libcurl/callbacks/hsts.md rename to transfers/callbacks/hsts.md diff --git a/libcurl/callbacks/openclosesocket.md b/transfers/callbacks/openclosesocket.md similarity index 100% rename from libcurl/callbacks/openclosesocket.md rename to transfers/callbacks/openclosesocket.md diff --git a/libcurl/callbacks/prereq.md b/transfers/callbacks/prereq.md similarity index 100% rename from libcurl/callbacks/prereq.md rename to transfers/callbacks/prereq.md diff --git a/libcurl/callbacks/progress.md b/transfers/callbacks/progress.md similarity index 100% rename from libcurl/callbacks/progress.md rename to transfers/callbacks/progress.md diff --git a/libcurl/callbacks/read.md b/transfers/callbacks/read.md similarity index 100% rename from libcurl/callbacks/read.md rename to transfers/callbacks/read.md diff --git a/libcurl/callbacks/resolver.md b/transfers/callbacks/resolver.md similarity index 100% rename from libcurl/callbacks/resolver.md rename to transfers/callbacks/resolver.md diff --git a/libcurl/callbacks/rtsp.md b/transfers/callbacks/rtsp.md similarity index 100% rename from libcurl/callbacks/rtsp.md rename to transfers/callbacks/rtsp.md diff --git a/libcurl/callbacks/seek.md b/transfers/callbacks/seek.md similarity index 100% rename from libcurl/callbacks/seek.md rename to transfers/callbacks/seek.md diff --git a/libcurl/callbacks/sockopt.md b/transfers/callbacks/sockopt.md similarity index 100% rename from libcurl/callbacks/sockopt.md rename to transfers/callbacks/sockopt.md diff --git a/libcurl/callbacks/sshkey.md b/transfers/callbacks/sshkey.md similarity index 100% rename from libcurl/callbacks/sshkey.md rename to transfers/callbacks/sshkey.md diff --git a/libcurl/callbacks/sslcontext.md b/transfers/callbacks/sslcontext.md similarity index 100% rename from libcurl/callbacks/sslcontext.md rename to transfers/callbacks/sslcontext.md diff --git a/libcurl/callbacks/trailers.md b/transfers/callbacks/trailers.md similarity index 100% rename from libcurl/callbacks/trailers.md rename to transfers/callbacks/trailers.md diff --git a/libcurl/callbacks/write.md b/transfers/callbacks/write.md similarity index 100% rename from libcurl/callbacks/write.md rename to transfers/callbacks/write.md diff --git a/libcurl/cleanup.md b/transfers/cleanup.md similarity index 100% rename from libcurl/cleanup.md rename to transfers/cleanup.md diff --git a/libcurl/conn.md b/transfers/conn/README.md similarity index 68% rename from libcurl/conn.md rename to transfers/conn/README.md index 97374ecab8..aca94c36da 100644 --- a/libcurl/conn.md +++ b/transfers/conn/README.md @@ -5,7 +5,7 @@ involved. A connection done using an Internet transport protocol like TCP or QUIC. Transfers are done *over* connections and libcurl offers a lot of concepts for connections and options to control how it works with them. - * [How libcurl connects](conn/how.md) - * [Connection reuse](conn/reuse.md) - * [Name resolving](conn/names.md) - * [Proxies](conn/proxies.md) + * [How libcurl connects](how.md) + * [Connection reuse](reuse.md) + * [Name resolving](names.md) + * [Proxies](proxies.md) diff --git a/libcurl/conn/how.md b/transfers/conn/how.md similarity index 100% rename from libcurl/conn/how.md rename to transfers/conn/how.md diff --git a/libcurl/conn/names.md b/transfers/conn/names.md similarity index 98% rename from libcurl/conn/names.md rename to transfers/conn/names.md index d5396467b6..e9d5c01090 100644 --- a/libcurl/conn/names.md +++ b/transfers/conn/names.md @@ -66,7 +66,8 @@ name is kept in the DNS cache. By default, each entry is kept in the cache for The DNS cache is kept within the easy handle when `curl_easy_perform` is used, or within the multi handle when the multi interface is used. It can also be -made shared between multiple easy handles using the [share interface](../sharing.md). +made shared between multiple easy handles using the +[share interface](../../helpers/sharing.md). ## Custom addresses for hosts diff --git a/libcurl/conn/proxies.md b/transfers/conn/proxies.md similarity index 100% rename from libcurl/conn/proxies.md rename to transfers/conn/proxies.md diff --git a/libcurl/conn/reuse.md b/transfers/conn/reuse.md similarity index 94% rename from libcurl/conn/reuse.md rename to transfers/conn/reuse.md index bb2edd8cfe..0c03b7b8a3 100644 --- a/libcurl/conn/reuse.md +++ b/transfers/conn/reuse.md @@ -31,5 +31,6 @@ later transfer. Just reuse the multi handle. ## Sharing the connection cache -Since libcurl 7.57.0, applications can use the [share interface](../sharing.md) +Since libcurl 7.57.0, applications can use the +[share interface](../../helpers/sharing.md) to have otherwise independent transfers share the same connection pool. diff --git a/transfers/control/README.md b/transfers/control/README.md new file mode 100644 index 0000000000..1ca582dd32 --- /dev/null +++ b/transfers/control/README.md @@ -0,0 +1,10 @@ +# Transfer control + +An ongoing transfer can be controlled in several ways. The following pages +describe further details: + +* [Stop](stop.md) +* [Stop slow transfers](stopslow.md) +* [Rate limit](ratelimit.md) +* [Progress meter](meter.md) +* [Progress callback](progress-callback.md) diff --git a/libcurl/control/meter.md b/transfers/control/meter.md similarity index 100% rename from libcurl/control/meter.md rename to transfers/control/meter.md diff --git a/libcurl/control/progress-callback.md b/transfers/control/progress-callback.md similarity index 100% rename from libcurl/control/progress-callback.md rename to transfers/control/progress-callback.md diff --git a/libcurl/control/ratelimit.md b/transfers/control/ratelimit.md similarity index 100% rename from libcurl/control/ratelimit.md rename to transfers/control/ratelimit.md diff --git a/libcurl/control/stop.md b/transfers/control/stop.md similarity index 91% rename from libcurl/control/stop.md rename to transfers/control/stop.md index bdcd1ee033..d43f94c8d0 100644 --- a/libcurl/control/stop.md +++ b/transfers/control/stop.md @@ -20,9 +20,9 @@ end: 1. return an error from a callback 2. set an option that makes the transfer stop after a fixed period of time -Every [callback](../callbacks.md) can return an error, and when an error is -returned from one of those functions the entire transfer is stopped. For -example the read, write or progress callbacks. +Every [callback](../callbacks/README.md) can return an error, and when an +error is returned from one of those functions the entire transfer is +stopped. For example the read, write or progress callbacks. The second way is to set a timeout or other option that stops the transfer after a time or at a particular condition. For example one or more of the diff --git a/libcurl/control/stopslow.md b/transfers/control/stopslow.md similarity index 100% rename from libcurl/control/stopslow.md rename to transfers/control/stopslow.md diff --git a/libcurl/drive.md b/transfers/drive/README.md similarity index 87% rename from libcurl/drive.md rename to transfers/drive/README.md index 315f6d62f9..d9467b6caf 100644 --- a/libcurl/drive.md +++ b/transfers/drive/README.md @@ -16,3 +16,7 @@ to scale up the number of simultaneous transfers to hundreds or thousands or so. Let's look at each one a little closer… + +* [Drive with easy](easy.md) +* [Drive with multi](multi.md) +* [Drive with multi\_socket](multi-socket.md) diff --git a/libcurl/drive/easy.md b/transfers/drive/easy.md similarity index 100% rename from libcurl/drive/easy.md rename to transfers/drive/easy.md diff --git a/libcurl/drive/multi-socket.md b/transfers/drive/multi-socket.md similarity index 100% rename from libcurl/drive/multi-socket.md rename to transfers/drive/multi-socket.md diff --git a/libcurl/drive/multi.md b/transfers/drive/multi.md similarity index 100% rename from libcurl/drive/multi.md rename to transfers/drive/multi.md diff --git a/libcurl/easyhandle.md b/transfers/easyhandle.md similarity index 94% rename from libcurl/easyhandle.md rename to transfers/easyhandle.md index f9e966524b..2dc1e88338 100644 --- a/libcurl/easyhandle.md +++ b/transfers/easyhandle.md @@ -21,7 +21,7 @@ syntax checking and validation of the input may also be postponed, so just because `curl_easy_setopt` did not complain, it does not mean that the input was correct and valid; you may get an error returned later. -Read more on [easy options](options.md) in its separate section. +Read more on [easy options](options/README.md) in its separate section. When you are done setting options to your easy handle, you can fire off the actual transfer. @@ -32,7 +32,7 @@ application and how libcurl is best integrated into your architecture. Those are further described later in this chapter. While the transfer is ongoing, libcurl calls your specified functions—known as -*[callbacks](callbacks.md)* — to deliver data, to read data and to do a +*[callbacks](callbacks/README.md)* — to deliver data, to read data and to do a variety of things. After the transfer has completed, you can figure out if it succeeded or not diff --git a/libcurl/getinfo.md b/transfers/getinfo.md similarity index 100% rename from libcurl/getinfo.md rename to transfers/getinfo.md diff --git a/libcurl/options.md b/transfers/options/README.md similarity index 92% rename from libcurl/options.md rename to transfers/options/README.md index 790e53e5ff..4714e4e5a8 100644 --- a/libcurl/options.md +++ b/transfers/options/README.md @@ -35,3 +35,9 @@ There is no way to extract the values previously set with `curl_easy_setopt()`. If you need to be able to extract the information again that you set earlier, we encourage you to keep track of that data yourself in your application. + +* [Set numerical options](num.md) +* [Set string options](strings.md) +* [TLS options](tls.md) +* [All options](all.md) +* [Get option information](info.md) diff --git a/libcurl/options/all.md b/transfers/options/all.md similarity index 100% rename from libcurl/options/all.md rename to transfers/options/all.md diff --git a/libcurl/options/info.md b/transfers/options/info.md similarity index 100% rename from libcurl/options/info.md rename to transfers/options/info.md diff --git a/libcurl/options/listall.pl b/transfers/options/listall.pl similarity index 100% rename from libcurl/options/listall.pl rename to transfers/options/listall.pl diff --git a/libcurl/options/num.md b/transfers/options/num.md similarity index 100% rename from libcurl/options/num.md rename to transfers/options/num.md diff --git a/libcurl/options/strings.md b/transfers/options/strings.md similarity index 100% rename from libcurl/options/strings.md rename to transfers/options/strings.md diff --git a/libcurl/options/tls.md b/transfers/options/tls.md similarity index 100% rename from libcurl/options/tls.md rename to transfers/options/tls.md diff --git a/usingcurl.md b/usingcurl.md deleted file mode 100644 index 5efc1a0d4b..0000000000 --- a/usingcurl.md +++ /dev/null @@ -1,32 +0,0 @@ -# Using curl - -Previous chapters have described some basic details on what curl is and -something about the basic command lines. You use command-line options and you -pass on URLs to work with. - -In this chapter, we are going to dive deeper into a variety of different -concepts of what the curl tool can do and how to tell curl to use these -features. You should consider all these features as different tools that are -here to help you do your file transfer tasks as conveniently as possible. - - * [Verbose](usingcurl/verbose.md) - * [Version](usingcurl/version.md) - * [Persistent connections](usingcurl/persist.md) - * [Downloads](usingcurl/downloads.md) - * [Uploads](usingcurl/uploads.md) - * [Transfer controls](usingcurl/transfers.md) - * [Connections](usingcurl/connections.md) - * [Timeouts](usingcurl/timeouts.md) - * [.netrc](usingcurl/netrc.md) - * [Proxies](usingcurl/proxies.md) - * [Exit status](usingcurl/returns.md) - * [TLS](usingcurl/tls.md) - * [SCP and SFTP](usingcurl/scpsftp.md) - * [Reading email](usingcurl/reademail.md) - * [Sending email](usingcurl/smtp.md) - * [DICT](usingcurl/dict.md) - * [IPFS](usingcurl/ipfs.md) - * [MQTT](usingcurl/mqtt.md) - * [TELNET](usingcurl/telnet.md) - * [TFTP](usingcurl/tftp.md) - * [Copy as curl](usingcurl/copyas.md) diff --git a/usingcurl/README.md b/usingcurl/README.md new file mode 100644 index 0000000000..7f07c3c49e --- /dev/null +++ b/usingcurl/README.md @@ -0,0 +1,28 @@ +# Command line transfers + +Previous chapters described curl concepts and something about the basic +command lines. You use command-line options and you pass on URLs to work with. + +In this chapter, we are going to dive deeper into doing actual transfers with +curl. What the curl tool can do and how to tell curl to use these features to +send or retrieve data for you. You should consider all these features as +different tools that are here to help you do your file transfer tasks as +conveniently as possible. + + * [Verbose](verbose/README.md) + * [Downloads](downloads/README.md) + * [Uploads](uploads.md) + * [Transfer controls](transfers/README.md) + * [Connections](connections/README.md) + * [Timeouts](timeouts.md) + * [.netrc](netrc.md) + * [Proxies](proxies/README.md) + * [TLS](tls.md) + * [SCP and SFTP](scpsftp.md) + * [Reading email](reademail.md) + * [Sending email](smtp.md) + * [DICT](dict.md) + * [IPFS](ipfs.md) + * [MQTT](mqtt.md) + * [TELNET](telnet.md) + * [TFTP](tftp.md) diff --git a/usingcurl/connections.md b/usingcurl/connections/README.md similarity index 67% rename from usingcurl/connections.md rename to usingcurl/connections/README.md index 392cc37944..69ae6da719 100644 --- a/usingcurl/connections.md +++ b/usingcurl/connections/README.md @@ -9,8 +9,8 @@ For ordinary command line usage, operating on a URL, these are details which are taken care of under the hood, and which you can mostly ignore. But at times you might find yourself wanting to tweak the specifics… -* [Name resolve tricks](connections/name.md) -* [Connection timeout](connections/timeout.md) -* [Network interface](connections/interface.md) -* [Local port number](connections/local-port.md) -* [Keep alive](connections/keepalive.md) +* [Name resolve tricks](name.md) +* [Connection timeout](timeout.md) +* [Network interface](interface.md) +* [Local port number](local-port.md) +* [Keep alive](keepalive.md) diff --git a/usingcurl/downloads.md b/usingcurl/downloads.md deleted file mode 100644 index 470732974b..0000000000 --- a/usingcurl/downloads.md +++ /dev/null @@ -1,23 +0,0 @@ -# Downloads - -"Download" means getting data from a server on a network, and the server is -then clearly considered to be "above" you. This is loading data down from the -server onto your machine where you are running curl. - -Downloading is probably the most common use case for curl — retrieving the -specific data pointed to by a URL onto your machine. - -* [What exactly is downloading?](downloads/whatis.md) -* [Storing downloads](downloads/storing.md) -* [Download to a file named by the URL](downloads/url-named.md) - * [Use the target filename from the server](downloads/content-disp.md) -* [HTML and charsets](downloads/charsets.md) -* [Compression](downloads/compression.md) -* [Shell redirects](downloads/redirects.md) -* [Multiple downloads](downloads/multiple.md) -* [My browser shows something else](downloads/browsers.md) -* [Maximum file size](downloads/max-filesize.md) -* [Storing metadata in file system](downloads/metadata-fs.md) -* [Raw](downloads/raw.md) -* [Retry](downloads/retry.md) -* [Resuming and ranges](downloads/resume.md) diff --git a/usingcurl/downloads/README.md b/usingcurl/downloads/README.md new file mode 100644 index 0000000000..d25c1b0e3a --- /dev/null +++ b/usingcurl/downloads/README.md @@ -0,0 +1,23 @@ +# Downloads + +"Download" means getting data from a server on a network, and the server is +then clearly considered to be "above" you. This is loading data down from the +server onto your machine where you are running curl. + +Downloading is probably the most common use case for curl — retrieving the +specific data pointed to by a URL onto your machine. + +* [What exactly is downloading?](whatis.md) +* [Storing downloads](storing.md) +* [Download to a file named by the URL](url-named.md) + * [Use the target filename from the server](content-disp.md) +* [HTML and charsets](charsets.md) +* [Compression](compression.md) +* [Shell redirects](redirects.md) +* [Multiple downloads](multiple.md) +* [My browser shows something else](browsers.md) +* [Maximum file size](max-filesize.md) +* [Storing metadata in file system](metadata-fs.md) +* [Raw](raw.md) +* [Retry](retry.md) +* [Resuming and ranges](resume.md) diff --git a/usingcurl/downloads/whatis.md b/usingcurl/downloads/whatis.md index 75cdb86acc..415c664cce 100644 --- a/usingcurl/downloads/whatis.md +++ b/usingcurl/downloads/whatis.md @@ -7,7 +7,7 @@ download. In this example the URL to download is `http://example.com`: curl http://example.com The URL is broken down into its individual components -([as explained elsewhere](../../cmdline/urls.md)), the correct server is +([as explained elsewhere](../../cmdline/urls/README.md)), the correct server is contacted and is then asked to deliver the specific resource—often a file. The server then delivers the data, or it refuses or perhaps the client asked for the wrong data and then that data is delivered. diff --git a/usingcurl/proxies.md b/usingcurl/proxies/README.md similarity index 53% rename from usingcurl/proxies.md rename to usingcurl/proxies/README.md index 77f8990b92..2c26cda963 100644 --- a/usingcurl/proxies.md +++ b/usingcurl/proxies/README.md @@ -11,15 +11,15 @@ then it runs off and do that and then it returns the data to you. There are several different types of proxies and we shall list and discuss them in subsections below. -* [Discover your proxy](proxies/discover.md) -* [PAC](proxies/pac.md) -* [Captive portals](proxies/captive.md) -* [Proxy type](proxies/type.md) -* [HTTP proxy](proxies/http.md) -* [SOCKS proxy](proxies/socks.md) -* [MITM proxy](proxies/mitm.md) -* [Authentication](proxies/auth.md) -* [HTTPS proxy](proxies/https.md) -* [Proxy environment variables](proxies/env.md) -* [Proxy headers](proxies/headers.md) -* [haproxy](proxies/haproxy.md) +* [Discover your proxy](discover.md) +* [PAC](pac.md) +* [Captive portals](captive.md) +* [Proxy type](type.md) +* [HTTP proxy](http.md) +* [SOCKS proxy](socks.md) +* [MITM proxy](mitm.md) +* [Authentication](auth.md) +* [HTTPS proxy](https.md) +* [Proxy environment variables](env.md) +* [Proxy headers](headers.md) +* [haproxy](haproxy.md) diff --git a/usingcurl/tls/backends.md b/usingcurl/tls/backends.md index 083c8f2253..d8ca8d2b5c 100644 --- a/usingcurl/tls/backends.md +++ b/usingcurl/tls/backends.md @@ -10,7 +10,7 @@ Sometimes features and behaviors differ slightly when curl is built with different TLS backends, but the developers work hard on making those differences as small and unnoticeable as possible. -Showing the curl version information with [curl --version](../version.md) +Showing the curl version information with [curl --version](../../cmdline/curlver.md) includes the TLS library and version in the first line of output. ## Multiple TLS backends diff --git a/usingcurl/transfers.md b/usingcurl/transfers/README.md similarity index 56% rename from usingcurl/transfers.md rename to usingcurl/transfers/README.md index 5616e8b91c..09029fff61 100644 --- a/usingcurl/transfers.md +++ b/usingcurl/transfers/README.md @@ -4,6 +4,6 @@ curl offers several different knobs and levers to control how transfers are performed. How fast to let them go, how slow to let them run and how to do multiple transfers. - * [Stop slow transfers](transfers/tooslow.md) - * [Rate limiting](transfers/rate-limiting.md) - * [Request rate limiting](transfers/request-rate.md) + * [Stop slow transfers](tooslow.md) + * [Rate limiting](rate-limiting.md) + * [Request rate limiting](request-rate.md) diff --git a/usingcurl/uploads.md b/usingcurl/uploads.md index 5a45b9ace0..8ebe517726 100644 --- a/usingcurl/uploads.md +++ b/usingcurl/uploads.md @@ -30,7 +30,7 @@ The upload kind is usually done with the `-d` or `--data` options, but there are a few additional alterations. Read the detailed description on how to do this with curl in the -[HTTP POST with curl](../http/post.md) chapter. +[HTTP POST with curl](../http/post/README.md) chapter. ### multipart formpost @@ -72,7 +72,7 @@ you have used locally, you specify it in the URL: curl -T uploadthis ftp://example.com/this/directory/remotename -Learn much more about FTPing in the [FTP with curl](../ftp.md) section. +Learn much more about FTPing in the [FTP with curl](../ftp/README.md) section. ## SMTP uploads diff --git a/usingcurl/verbose.md b/usingcurl/verbose/README.md similarity index 98% rename from usingcurl/verbose.md rename to usingcurl/verbose/README.md index cd75c78bf1..6e82554bf4 100644 --- a/usingcurl/verbose.md +++ b/usingcurl/verbose/README.md @@ -110,3 +110,6 @@ outputs the downloaded data you ask it to. With silence activated, you can ask for it to still output the error message on failures by adding `-S` or `--show-error`. + + * [Trace options](trace.md) + * [Write out](writeout.md)