From a71288072b84ffd844107ba777eca889f810ba3a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 14 Jun 2023 15:37:53 +0200 Subject: [PATCH] docs/libcurl/libcurl.3: cleanups and improvements Closes #11317 --- docs/libcurl/libcurl.3 | 58 ++++++++++++++++++++---------------------- 1 file changed, 27 insertions(+), 31 deletions(-) diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 index 848afcb4ca..ae8571a0ba 100644 --- a/docs/libcurl/libcurl.3 +++ b/docs/libcurl/libcurl.3 @@ -28,21 +28,12 @@ libcurl \- client-side URL transfers This is a short overview on how to use libcurl in your C programs. There are specific man pages for each function mentioned in here. See \fIlibcurl-easy(3)\fP, \fIlibcurl-multi(3)\fP, \fIlibcurl-share(3)\fP, -\fIlibcurl-url(3)\fP and \fIlibcurl-tutorial(3)\fP for in-depth understanding -on how to program with libcurl. +\fIlibcurl-url(3)\fP, \fIlibcurl-ws(3)\fP and \fIlibcurl-tutorial(3)\fP for +in-depth understanding on how to program with libcurl. There are many bindings available that bring libcurl access to your favorite language. Look elsewhere for documentation on those. - -libcurl has a global constant environment that you must set up and maintain -while using libcurl. This essentially means you call \fIcurl_global_init(3)\fP -at the start of your program and \fIcurl_global_cleanup(3)\fP at the end. See -\fBGLOBAL CONSTANTS\fP below for details. - -If libcurl was compiled with support for multiple SSL backends, the function -\fIcurl_global_sslset(3)\fP can be called before \fIcurl_global_init(3)\fP -to select the active SSL backend. - +.SH TRANSFERS To transfer files, you create an "easy handle" using \fIcurl_easy_init(3)\fP for a single individual transfer (in either direction). You then set your desired set of options in that handle with \fIcurl_easy_setopt(3)\fP. Options @@ -65,28 +56,29 @@ similar. The multi interface allows you to select() on libcurl action, and even to easily download multiple files simultaneously using a single thread. See further details in the \fIlibcurl-multi(3)\fP man page. +.SH "SUPPORT INTERFACES" +There is also a series of other helpful functions and interface families to +use, including these: +.RS +.IP curl_version_info() +gets detailed libcurl (and other used libraries) version info. See +\fIcurl_version_info(3)\fP +.IP curl_getdate() +converts a date string to time_t. See \fIcurl_getdate(3)\fP +.IP curl_easy_getinfo() +get information about a performed transfer. See \fIcurl_easy_getinfo(3)\fP +.IP curl_mime_addpart() +helps building an HTTP form POST. See \fIcurl_mime_addpart(3)\fP +.IP curl_slist_append() +builds a linked list. See \fIcurl_slist_append(3)\fP +.IP Sharing data between transfers You can have multiple easy handles share certain data, even if they are used in different threads. This magic is setup using the share interface, as described in the \fIlibcurl-share(3)\fP man page. - -There is also a series of other helpful functions to use, including these: -.RS -.IP curl_version_info() -gets detailed libcurl (and other used libraries) version info -.IP curl_getdate() -converts a date string to time_t -.IP curl_easy_getinfo() -get information about a performed transfer -.IP curl_formadd() -helps building an HTTP form POST -.IP curl_formfree() -free a list built with \fIcurl_formadd(3)\fP -.IP curl_slist_append() -builds a linked list -.IP curl_slist_free_all() -frees a whole curl_slist -.IP curl_url_set() -parses a URL +.IP "URL Parsing" +URL parsing and manipulations. See \fIlibcurl-url(3)\fP +.IP "WebSocket communication" +See \fIlibcurl-ws(3)\fP .RE .SH "LINKING WITH LIBCURL" @@ -154,6 +146,10 @@ that library that describes the SSL protocol. allocate resources (e.g. the memory for the GNU TLS tree mentioned above), so the companion function \fIcurl_global_cleanup(3)\fP releases them. +If libcurl was compiled with support for multiple SSL backends, the function +\fIcurl_global_sslset(3)\fP can be called before \fIcurl_global_init(3)\fP +to select the active SSL backend. + The global constant functions are thread-safe since libcurl 7.84.0 if \fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set (most platforms). Read \fIlibcurl-thread(3)\fP for thread safety guidelines.