Penguin
Recent Changes
Annotated edit history of libcurl(5) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 libcurl
2 !!!libcurl
3 NAME
4 DESCRIPTION
5 LINKING WITH LIBCURL
6 LIBCURL SYMBOL NAMES
7 PORTABILITY
8 THREADS
9 PERSISTANT CONNECTIONS
10 COMPATIBILITY WITH OLDER LIBCURLS
11 ----
12 !!NAME
13
14
15 libcurl - client-side URL transfers
16 !!DESCRIPTION
17
18
19 This is an overview on how to use libcurl in your C
20 programs. There are specific man pages for each function
21 mentioned in here. There's also the libcurl-the-guide
22 document for a complete tutorial to programming with
23 libcurl.
24
25
26 libcurl can also be used directly from within your Java,
27 PHP, Perl, Ruby or Tcl programs as well, look elsewhere for
28 documentation on this!
29
30
31 All applications that use libcurl should call
32 ''curl_global_init()'' exactly once before any libcurl
33 function can be used. After all usage of libcurl is
34 complete, it __must__ call ''curl_global_cleanup()''.
35 In between those two calls, you can use libcurl as described
36 below.
37
38
39 When using libcurl you init your session and get a handle,
40 which you use as input to the following interface functions
41 you use. Use ''curl_easy_init()'' to get the
42 handle.
43
44
45 You continue by setting all the options you want in the
46 upcoming transfer, most important among them is the URL
47 itself (you can't transfer anything without a specified URL
48 as you may have figured out yourself). You might want to set
49 some callbacks as well that will be called from the library
50 when data is available etc. ''curl_easy_setopt()'' is
51 there for this.
52
53
54 When all is setup, you tell libcurl to perform the transfer
55 using ''curl_easy_perform()''. It will then do the entire
56 operation and won't return until it is done (successfully or
57 not).
58
59
60 After the transfer has been made, you can set new options
61 and make another transfer, or if you're done, cleanup the
62 session by calling ''curl_easy_cleanup()''. If you want
63 persistant connections, you don't cleanup immediately, but
64 instead run ahead and perform other transfers using the same
65 handle. See the chapter below for Persistant
66 Connections.
67
68
69 There is also a series of other helpful functions to use.
70 They are:
71
72
73 __curl_version()__
74
75
76 displays the libcurl version
77
78
79 __curl_getdate()__
80
81
82 converts a date string to time_t
83
84
85 __curl_getenv()__
86
87
88 portable environment variable reader
89
90
91 __curl_easy_getinfo()__
92
93
94 get information about a performed transfer
95
96
97 __curl_formadd()__
98
99
100 helps building a HTTP form POST
101
102
103 __curl_formfree()__
104
105
106 free a list built with
107 curl_formparse()/curl_formadd()
108
109
110 __curl_slist_append()__
111
112
113 builds a linked list
114
115
116 __curl_slist_free_all()__
117
118
119 frees a whole curl_slist
120
121
122 __curl_mprintf()__
123
124
125 portable printf() functions
126
127
128 __curl_strequal()__
129
130
131 portable case insensitive string comparisons
132 !!LINKING WITH LIBCURL
133
134
135 Starting with 7.7.2 (on unix-like machines), there's a tool
136 named curl-config that gets installed with the rest of the
137 curl stuff when 'make install' is performed.
138
139
140 curl-config is added to make it easier for applications to
141 link with libcurl and developers to learn about libcurl and
142 how to use it.
143
144
145 Run 'curl-config --libs' to get the (additional) linker
146 options you need to link with the particular version of
147 libcurl you've installed.
148
149
150 For details, see the curl-config.1 man page.
151 !!LIBCURL SYMBOL NAMES
152
153
154 All public functions in the libcurl interface are prefixed
155 with 'curl_' (with a lowercase c). You can find other
156 functions in the library source code, but other prefixes
157 indicate the functions are private and may change without
158 further notice in the next release.
159
160
161 Only use documented functions and
162 functionality!
163 !!PORTABILITY
164
165
166 libcurl works __exactly__ the same, on any of the
167 platforms it compiles and builds on.
168
169
170 There's only one caution, and that is the win32 platform
171 that may(*) require you to init the winsock stuff before you
172 use the libcurl functions. Details on this are noted on the
173 curl_easy_init() man page.
174
175
176 (*) = it appears as if users of the cygwin environment get
177 this done automatically, also libcurl 7.8.1 and later can
178 handle this for you.
179 !!THREADS
180
181
182 Never ever call curl-functions simultaneously using the same
183 handle from several threads. libcurl is thread-safe and can
184 be used in any number of threads, but you must use separate
185 curl handles if you want to use libcurl in more than one
186 thread simultaneously.
187 !!PERSISTANT CONNECTIONS
188
189
190 With libcurl 7.7, persistant connections were added.
191 Persistant connections means that libcurl can re-use the
192 same connection for several transfers, if the conditions are
193 right.
194
195
196 libcurl will *always* attempt to use persistant connections.
197 Whenever you use curl_easy_perform(), libcurl will attempt
198 to use an existing connection to do the transfer, and if
199 none exists it'll open a new one that will be subject for
200 re-use on a possible following call to
201 curl_easy_perform().
202
203
204 To allow libcurl to take full advantage of persistant
205 connections, you should do as many of your file transfers as
206 possible using the same curl handle. When you call
207 curl_easy_cleanup(), all the possibly open connections held
208 by libcurl will be closed and forgotten.
209
210
211 Note that the options set with curl_easy_setopt() will be
212 used in on every repeat curl_easy_perform()
213 call
214 !!COMPATIBILITY WITH OLDER LIBCURLS
215
216
217 Repeated curl_easy_perform() calls on the same handle were
218 not supported in pre-7.7 versions, and caused confusion and
219 undefined behaviour.
220 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.