diff options
Diffstat (limited to 'docs/libcurl/libcurl.3')
| -rw-r--r-- | docs/libcurl/libcurl.3 | 228 |
1 files changed, 0 insertions, 228 deletions
diff --git a/docs/libcurl/libcurl.3 b/docs/libcurl/libcurl.3 deleted file mode 100644 index 1c1740663..000000000 --- a/docs/libcurl/libcurl.3 +++ /dev/null @@ -1,228 +0,0 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. -.\" * -.\" * This software is licensed as described in the file COPYING, which -.\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.se/docs/copyright.html. -.\" * -.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell -.\" * copies of the Software, and permit persons to whom the Software is -.\" * furnished to do so, under the terms of the COPYING file. -.\" * -.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY -.\" * KIND, either express or implied. -.\" * -.\" * SPDX-License-Identifier: curl -.\" * -.\" ************************************************************************** -.TH libcurl 3 "March 19, 2002" "libcurl" "libcurl" -.SH NAME -libcurl \- client-side URL transfers -.SH DESCRIPTION -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, \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. -.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 -you set with \fIcurl_easy_setopt(3)\fP stick. They are then used for every -repeated use of this handle until you either change the option, or you reset -them all with \fIcurl_easy_reset(3)\fP. - -To actually transfer data you have the option of using the "easy" interface, -or the "multi" interface. - -The easy interface is a synchronous interface with which you call -\fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is -completed, the function returns and you can continue. More details are found in -the \fIlibcurl-easy(3)\fP man page. - -The multi interface on the other hand is an asynchronous interface, that you -call and that performs only a little piece of the transfer on each invoke. It -is perfect if you want to do things while the transfer is in progress, or -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. -.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" -On unix-like machines, there is a tool named curl-config that gets installed -with the rest of the curl stuff when 'make install' is performed. - -curl-config is added to make it easier for applications to link with libcurl -and developers to learn about libcurl and how to use it. - -Run 'curl-config --libs' to get the (additional) linker options you need to -link with the particular version of libcurl you have installed. See the -\fIcurl-config(1)\fP man page for further details. - -Unix-like operating system that ship libcurl as part of their distributions -often do not provide the curl-config tool, but simply install the library and -headers in the common path for this purpose. - -Many Linux and similar systems use pkg-config to provide build and link -options about libraries and libcurl supports that as well. -.SH "LIBCURL SYMBOL NAMES" -All public functions in the libcurl interface are prefixed with 'curl_' (with -a lowercase c). You can find other functions in the library source code, but -other prefixes indicate that the functions are private and may change without -further notice in the next release. - -Only use documented functions and functionality! -.SH "PORTABILITY" -libcurl works -.B exactly -the same, on any of the platforms it compiles and builds on. -.SH "THREADS" -libcurl is thread safe but there are a few exceptions. Refer to -\fIlibcurl-thread(3)\fP for more information. - -.SH "PERSISTENT CONNECTIONS" -Persistent connections means that libcurl can reuse the same connection for -several transfers, if the conditions are right. - -libcurl always attempts to use persistent connections. Whenever you use -\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl -attempts to use an existing connection to do the transfer, and if none exists -it opens a new one that is subject for reuse on a possible following call to -\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. - -To allow libcurl to take full advantage of persistent connections, you should -do as many of your file transfers as possible using the same handle. - -If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all -the possibly open connections held by libcurl are closed and forgotten. - -When you have created a multi handle and are using the multi interface, the -connection pool is instead kept in the multi handle so closing and creating -new easy handles to do transfers do not affect them. Instead all added easy -handles can take advantage of the single shared pool. -.SH "GLOBAL CONSTANTS" -There are a variety of constants that libcurl uses, mainly through its -internal use of other libraries, which are too complicated for the -library loader to set up. Therefore, a program must call a library -function after the program is loaded and running to finish setting up -the library code. For example, when libcurl is built for SSL -capability via the GNU TLS library, there is an elaborate tree inside -that library that describes the SSL protocol. - -\fIcurl_global_init(3)\fP is the function that you must call. This may -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. - -If the global constant functions are \fInot thread safe\fP, then you must -not call them when any other thread in the program is running. It -is not good enough that no other thread is using libcurl at the time, -because these functions internally call similar functions of other -libraries, and those functions are similarly thread-unsafe. You cannot -generally know what these libraries are, or whether other threads are -using them. - -If the global constant functions are \fInot thread safe\fP, then the basic rule -for constructing a program that uses libcurl is this: Call -\fIcurl_global_init(3)\fP, with a \fICURL_GLOBAL_ALL\fP argument, immediately -after the program starts, while it is still only one thread and before it uses -libcurl at all. Call \fIcurl_global_cleanup(3)\fP immediately before the -program exits, when the program is again only one thread and after its last -use of libcurl. - -It is not actually required that the functions be called at the beginning -and end of the program -- that is just usually the easiest way to do it. - -You can call both of these multiple times, as long as all calls meet -these requirements and the number of calls to each is the same. - -The global constant situation merits special consideration when the -code you are writing to use libcurl is not the main program, but rather -a modular piece of a program, e.g. another library. As a module, -your code does not know about other parts of the program -- it does not -know whether they use libcurl or not. And its code does not necessarily -run at the start and end of the whole program. - -A module like this must have global constant functions of its own, just like -\fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus -has control at the beginning and end of the program and has a place to call -the libcurl functions. If multiple modules in the program use libcurl, they -all separately call the libcurl functions, and that is OK because only the -first \fIcurl_global_init(3)\fP and the last \fIcurl_global_cleanup(3)\fP in a -program change anything. (libcurl uses a reference count in static memory). - -In a C++ module, it is common to deal with the global constant situation by -defining a special class that represents the global constant environment of -the module. A program always has exactly one object of the class, in static -storage. That way, the program automatically calls the constructor of the -object as the program starts up and the destructor as it terminates. As the -author of this libcurl-using module, you can make the constructor call -\fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP -and satisfy libcurl's requirements without your user having to think about it. -(Caveat: If you are initializing libcurl from a Windows DLL you should not -initialize it from \fIDllMain\fP or a static initializer because Windows holds -the loader lock during that time and it could cause a deadlock.) - -\fIcurl_global_init(3)\fP has an argument that tells what particular parts of -the global constant environment to set up. In order to successfully use any -value except \fICURL_GLOBAL_ALL\fP (which says to set up the whole thing), you -must have specific knowledge of internal workings of libcurl and all other -parts of the program of which it is part. - -A special part of the global constant environment is the identity of the -memory allocator. \fIcurl_global_init(3)\fP selects the system default memory -allocator, but you can use \fIcurl_global_init_mem(3)\fP to supply one of your -own. However, there is no way to use \fIcurl_global_init_mem(3)\fP in a -modular program -- all modules in the program that might use libcurl would -have to agree on one allocator. - -There is a failsafe in libcurl that makes it usable in simple situations -without you having to worry about the global constant environment at all: -\fIcurl_easy_init(3)\fP sets up the environment itself if it has not been done -yet. The resources it acquires to do so get released by the operating system -automatically when the program exits. - -This failsafe feature exists mainly for backward compatibility because there -was a time when the global functions did not exist. Because it is sufficient -only in the simplest of programs, it is not recommended for any program to -rely on it. |