Annotation of embedaddon/curl/docs/libcurl/libcurl.3, revision 1.1.1.1
1.1 misho 1: .\" **************************************************************************
2: .\" * _ _ ____ _
3: .\" * Project ___| | | | _ \| |
4: .\" * / __| | | | |_) | |
5: .\" * | (__| |_| | _ <| |___
6: .\" * \___|\___/|_| \_\_____|
7: .\" *
8: .\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al.
9: .\" *
10: .\" * This software is licensed as described in the file COPYING, which
11: .\" * you should have received as part of this distribution. The terms
12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
13: .\" *
14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
15: .\" * copies of the Software, and permit persons to whom the Software is
16: .\" * furnished to do so, under the terms of the COPYING file.
17: .\" *
18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
19: .\" * KIND, either express or implied.
20: .\" *
21: .\" **************************************************************************
22: .TH libcurl 3 "March 23, 2020" "libcurl 7.70.0" "libcurl overview"
23:
24: .SH NAME
25: libcurl \- client-side URL transfers
26: .SH DESCRIPTION
27: This is a short overview on how to use libcurl in your C programs. There are
28: specific man pages for each function mentioned in here. There are also the
29: \fIlibcurl-easy(3)\fP man page, the \fIlibcurl-multi(3)\fP man page, the
30: \fIlibcurl-share(3)\fP man page and the \fIlibcurl-tutorial(3)\fP man page for
31: in-depth understanding on how to program with libcurl.
32:
33: There are many bindings available that bring libcurl access to your favourite
34: language. Look elsewhere for documentation on those.
35:
36: libcurl has a global constant environment that you must set up and maintain
37: while using libcurl. This essentially means you call
38: \fIcurl_global_init(3)\fP at the start of your program and
39: \fIcurl_global_cleanup(3)\fP at the end. See \fBGLOBAL CONSTANTS\fP below for
40: details.
41:
42: If libcurl was compiled with support for multiple SSL backends, the function
43: \fIcurl_global_sslset(3)\fP can be called before \fIcurl_global_init(3)\fP
44: to select the active SSL backend.
45:
46: To transfer files, you create an "easy handle" using \fIcurl_easy_init(3)\fP
47: for a single individual transfer (in either direction). You then set your
48: desired set of options in that handle with \fIcurl_easy_setopt(3)\fP. Options
49: you set with \fIcurl_easy_setopt(3)\fP stick. They will be used on every
50: repeated use of this handle until you either change the option, or you reset
51: them all with \fIcurl_easy_reset(3)\fP.
52:
53: To actually transfer data you have the option of using the "easy" interface,
54: or the "multi" interface.
55:
56: The easy interface is a synchronous interface with which you call
57: \fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is
58: completed, the function returns and you can continue. More details are found in
59: the \fIlibcurl-easy(3)\fP man page.
60:
61: The multi interface on the other hand is an asynchronous interface, that you
62: call and that performs only a little piece of the transfer on each invoke. It
63: is perfect if you want to do things while the transfer is in progress, or
64: similar. The multi interface allows you to select() on libcurl action, and
65: even to easily download multiple files simultaneously using a single
66: thread. See further details in the \fIlibcurl-multi(3)\fP man page.
67:
68: You can have multiple easy handles share certain data, even if they are used
69: in different threads. This magic is setup using the share interface, as
70: described in the \fIlibcurl-share(3)\fP man page.
71:
72: There is also a series of other helpful functions to use, including these:
73: .RS
74: .IP curl_version_info()
75: gets detailed libcurl (and other used libraries) version info
76: .IP curl_getdate()
77: converts a date string to time_t
78: .IP curl_easy_getinfo()
79: get information about a performed transfer
80: .IP curl_formadd()
81: helps building an HTTP form POST
82: .IP curl_formfree()
83: free a list built with \fIcurl_formadd(3)\fP
84: .IP curl_slist_append()
85: builds a linked list
86: .IP curl_slist_free_all()
87: frees a whole curl_slist
88: .RE
89:
90: .SH "LINKING WITH LIBCURL"
91: On unix-like machines, there's a tool named curl-config that gets installed
92: with the rest of the curl stuff when 'make install' is performed.
93:
94: curl-config is added to make it easier for applications to link with libcurl
95: and developers to learn about libcurl and how to use it.
96:
97: Run 'curl-config --libs' to get the (additional) linker options you need to
98: link with the particular version of libcurl you've installed. See the
99: \fIcurl-config(1)\fP man page for further details.
100:
101: Unix-like operating system that ship libcurl as part of their distributions
102: often don't provide the curl-config tool, but simply install the library and
103: headers in the common path for this purpose.
104:
105: Many Linux and similar systems use pkg-config to provide build and link
106: options about libraries and libcurl supports that as well.
107: .SH "LIBCURL SYMBOL NAMES"
108: All public functions in the libcurl interface are prefixed with 'curl_' (with
109: a lowercase c). You can find other functions in the library source code, but
110: other prefixes indicate that the functions are private and may change without
111: further notice in the next release.
112:
113: Only use documented functions and functionality!
114: .SH "PORTABILITY"
115: libcurl works
116: .B exactly
117: the same, on any of the platforms it compiles and builds on.
118: .SH "THREADS"
119: libcurl is thread safe but there are a few exceptions. Refer to
120: \fIlibcurl-thread(3)\fP for more information.
121:
122: .SH "PERSISTENT CONNECTIONS"
123: Persistent connections means that libcurl can re-use the same connection for
124: several transfers, if the conditions are right.
125:
126: libcurl will \fBalways\fP attempt to use persistent connections. Whenever you
127: use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl
128: will attempt to use an existing connection to do the transfer, and if none
129: exists it'll open a new one that will be subject for re-use on a possible
130: following call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP.
131:
132: To allow libcurl to take full advantage of persistent connections, you should
133: do as many of your file transfers as possible using the same handle.
134:
135: If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all
136: the possibly open connections held by libcurl will be closed and forgotten.
137:
138: When you've created a multi handle and are using the multi interface, the
139: connection pool is instead kept in the multi handle so closing and creating
140: new easy handles to do transfers will not affect them. Instead all added easy
141: handles can take advantage of the single shared pool.
142: .SH "GLOBAL CONSTANTS"
143: There are a variety of constants that libcurl uses, mainly through its
144: internal use of other libraries, which are too complicated for the
145: library loader to set up. Therefore, a program must call a library
146: function after the program is loaded and running to finish setting up
147: the library code. For example, when libcurl is built for SSL
148: capability via the GNU TLS library, there is an elaborate tree inside
149: that library that describes the SSL protocol.
150:
151: \fIcurl_global_init(3)\fP is the function that you must call. This may
152: allocate resources (e.g. the memory for the GNU TLS tree mentioned above), so
153: the companion function \fIcurl_global_cleanup(3)\fP releases them.
154:
155: The basic rule for constructing a program that uses libcurl is this: Call
156: \fIcurl_global_init(3)\fP, with a \fICURL_GLOBAL_ALL\fP argument, immediately
157: after the program starts, while it is still only one thread and before it uses
158: libcurl at all. Call \fIcurl_global_cleanup(3)\fP immediately before the
159: program exits, when the program is again only one thread and after its last
160: use of libcurl.
161:
162: You can call both of these multiple times, as long as all calls meet
163: these requirements and the number of calls to each is the same.
164:
165: It isn't actually required that the functions be called at the beginning
166: and end of the program -- that's just usually the easiest way to do it.
167: It \fIis\fP required that the functions be called when no other thread
168: in the program is running.
169:
170: These global constant functions are \fInot thread safe\fP, so you must
171: not call them when any other thread in the program is running. It
172: isn't good enough that no other thread is using libcurl at the time,
173: because these functions internally call similar functions of other
174: libraries, and those functions are similarly thread-unsafe. You can't
175: generally know what these libraries are, or whether other threads are
176: using them.
177:
178: The global constant situation merits special consideration when the
179: code you are writing to use libcurl is not the main program, but rather
180: a modular piece of a program, e.g. another library. As a module,
181: your code doesn't know about other parts of the program -- it doesn't
182: know whether they use libcurl or not. And its code doesn't necessarily
183: run at the start and end of the whole program.
184:
185: A module like this must have global constant functions of its own, just like
186: \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus
187: has control at the beginning and end of the program and has a place to call
188: the libcurl functions. Note that if multiple modules in the program use
189: libcurl, they all will separately call the libcurl functions, and that's OK
190: because only the first \fIcurl_global_init(3)\fP and the last
191: \fIcurl_global_cleanup(3)\fP in a program change anything. (libcurl uses a
192: reference count in static memory).
193:
194: In a C++ module, it is common to deal with the global constant situation by
195: defining a special class that represents the global constant environment of
196: the module. A program always has exactly one object of the class, in static
197: storage. That way, the program automatically calls the constructor of the
198: object as the program starts up and the destructor as it terminates. As the
199: author of this libcurl-using module, you can make the constructor call
200: \fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP
201: and satisfy libcurl's requirements without your user having to think about it.
202: (Caveat: If you are initializing libcurl from a Windows DLL you should not
203: initialize it from DllMain or a static initializer because Windows holds the
204: loader lock during that time and it could cause a deadlock.)
205:
206: \fIcurl_global_init(3)\fP has an argument that tells what particular parts of
207: the global constant environment to set up. In order to successfully use any
208: value except \fICURL_GLOBAL_ALL\fP (which says to set up the whole thing), you
209: must have specific knowledge of internal workings of libcurl and all other
210: parts of the program of which it is part.
211:
212: A special part of the global constant environment is the identity of the
213: memory allocator. \fIcurl_global_init(3)\fP selects the system default memory
214: allocator, but you can use \fIcurl_global_init_mem(3)\fP to supply one of your
215: own. However, there is no way to use \fIcurl_global_init_mem(3)\fP in a
216: modular program -- all modules in the program that might use libcurl would
217: have to agree on one allocator.
218:
219: There is a failsafe in libcurl that makes it usable in simple situations
220: without you having to worry about the global constant environment at all:
221: \fIcurl_easy_init(3)\fP sets up the environment itself if it hasn't been done
222: yet. The resources it acquires to do so get released by the operating system
223: automatically when the program exits.
224:
225: This failsafe feature exists mainly for backward compatibility because
226: there was a time when the global functions didn't exist. Because it
227: is sufficient only in the simplest of programs, it is not recommended
228: for any program to rely on it.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to libcurl.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl