1WWW::Curl(3) User Contributed Perl Documentation WWW::Curl(3)
2
3
4
6 WWW::Curl - Perl extension interface for libcurl
7
9 use WWW::Curl;
10 print $WWW::Curl::VERSION;
11
13 WWW::Curl is a Perl extension interface for libcurl.
14
16 This module provides a Perl interface to libcurl. It is not intended to
17 be a standalone module and because of this, the main libcurl
18 documentation should be consulted for API details at
19 <http://curl.haxx.se>. The documentation you're reading right now only
20 contains the Perl specific details, some sample code and the
21 differences between the C API and the Perl one.
22
24 The name might be confusing, it originates from libcurl. This is not an
25 ::Easy module in the sense normally used on CPAN.
26
27 Here is a small snippet of making a request with WWW::Curl::Easy.
28
29 use strict;
30 use warnings;
31 use WWW::Curl::Easy;
32
33 my $curl = WWW::Curl::Easy->new;
34
35 $curl->setopt(CURLOPT_HEADER,1);
36 $curl->setopt(CURLOPT_URL, 'http://example.com');
37
38 # A filehandle, reference to a scalar or reference to a typeglob can be used here.
39 my $response_body;
40 $curl->setopt(CURLOPT_WRITEDATA,\$response_body);
41
42 # Starts the actual request
43 my $retcode = $curl->perform;
44
45 # Looking at the results...
46 if ($retcode == 0) {
47 print("Transfer went ok\n");
48 my $response_code = $curl->getinfo(CURLINFO_HTTP_CODE);
49 # judge result and next action based on $response_code
50 print("Received response: $response_body\n");
51 } else {
52 # Error code, type of error, error message
53 print("An error happened: $retcode ".$curl->strerror($retcode)." ".$curl->errbuf."\n");
54 }
55
56 See curl_easy_setopt(3) for details of "setopt()".
57
59 use strict;
60 use warnings;
61 use WWW::Curl::Easy;
62 use WWW::Curl::Multi;
63
64 my %easy;
65 my $curl = WWW::Curl::Easy->new;
66 my $curl_id = '13'; # This should be a handle unique id.
67 $easy{$curl_id} = $curl;
68 my $active_handles = 0;
69
70 $curl->setopt(CURLOPT_PRIVATE,$curl_id);
71 # do the usual configuration on the handle
72 ...
73
74 my $curlm = WWW::Curl::Multi->new;
75
76 # Add some easy handles
77 $curlm->add_handle($curl);
78 $active_handles++;
79
80 while ($active_handles) {
81 my $active_transfers = $curlm->perform;
82 if ($active_transfers != $active_handles) {
83 while (my ($id,$return_value) = $curlm->info_read) {
84 if ($id) {
85 $active_handles--;
86 my $actual_easy_handle = $easy{$id};
87 # do the usual result/error checking routine here
88 ...
89 # letting the curl handle get garbage collected, or we leak memory.
90 delete $easy{$id};
91 }
92 }
93 }
94 }
95
96 This interface is different than what the C API does. $curlm->perform
97 is non-blocking and performs requests in parallel. The method does a
98 little work and then returns control, therefor it has to be called
99 periodically to get the job done. It's return value is the number of
100 unfinished requests.
101
102 When the number of unfinished requests changes compared to the number
103 of active handles, $curlm->info_read should be checked for finished
104 requests. It returns one handle and it's return value at a time, or an
105 empty list if there are no more finished requests. $curlm->info_read
106 calls remove_handle on the given easy handle automatically, internally.
107 The easy handle will still remain available until it goes out of scope,
108 this action just detaches it from multi.
109
110 Please make sure that the easy handle does not get garbage collected
111 until after the multi handle finishes processing it, or bad things
112 happen.
113
114 The multi handle does not need to be cleaned up, when it goes out of
115 scope it calls the required cleanup methods automatically.
116
117 It is possible to use $curlm->add_handle to add further requests to be
118 processed after $curlm->perform has been called. WWW::Curl::Multi
119 doesn't care about the order. It is possible to process all requests
120 for a multi handle and then add a new batch of easy handles for
121 processing.
122
124 use WWW::Curl::Share;
125 my $curlsh = new WWW::Curl::Share;
126 $curlsh->setopt(CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
127 $curlsh->setopt(CURLSHOPT_SHARE, CURL_LOCK_DATA_DNS);
128 $curl->setopt(CURLOPT_SHARE, $curlsh);
129 $curlsh->setopt(CURLSHOPT_UNSHARE, CURL_LOCK_DATA_COOKIE);
130 $curlsh->setopt(CURLSHOPT_UNSHARE, CURL_LOCK_DATA_DNS);
131
132 WWW::Curl::Share is an extension to WWW::Curl::Easy which makes it
133 possible to use a single cookies/dns cache for several Easy handles.
134
135 It's usable methods are:
136
137 $curlsh = new WWW::Curl::Share
138 This method constructs a new WWW::Curl::Share object.
139
140 $curlsh->setopt(CURLSHOPT_SHARE, $value );
141 Enables share for:
142 CURL_LOCK_DATA_COOKIE use single cookies database
143 CURL_LOCK_DATA_DNS use single DNS cache
144 $curlsh->setopt(CURLSHOPT_UNSHARE, $value );
145 Disable share for given $value (see CURLSHOPT_SHARE)
146
147 $curlsh->strerror( ErrNo )
148 This method returns a string describing the CURLSHcode error
149 code passed in the argument errornum.
150
151 This is how you enable sharing for a specific WWW::Curl::Easy handle:
152
153 $curl->setopt(CURLOPT_SHARE, $curlsh)
154 Attach share object to WWW::Curl::Easy instance
155
157 use WWW::Curl::Form;
158 my $curlf = WWW::Curl::Form->new;
159 $curlf->formaddfile($filename, 'attachment', "multipart/form-data");
160 $curlf->formadd("FIELDNAME", "VALUE");
161
162 $curl->setopt(CURLOPT_HTTPPOST, $curlf);
163
164 Its usable methods are:
165
166 $curlf = new WWW::Curl::Form
167 This method constructs a new WWW::Curl::Form object.
168
169 $curlf->formadd(FIELDNAME, VALUE)
170 This method adds a field with a given value, to the form that is being submitted.
171
172 $curlf->formaddfile(FILENAME, DESCRIPTION, TYPE)
173 This method will add a file to the form. The description is the name of the field
174 that you form expects the data to be submitted in.
175
177 curl_easy_setopt
178 Most of the options should work, however some might not. Please
179 send reports, tests and patches to fix those.
180
181 curl_easy_escape
182 Not implemented. Since equivalent Perl code is easily produced,
183 this method will only made available for interface completeness, if
184 ever.
185
186 curl_easy_init
187 Used only internally. The standard Perl way of initializing an
188 object should be used,
189 "my $curl = WWW::Curl::Easy->new;".
190
191 curl_easy_cleanup
192 Used only internally. Curl object cleanup happens when the handle
193 goes out of scope.
194
195 curl_easy_duphandle
196 Should be working for most cases, however do not change the value
197 of options which accept a list/arrayref value on a duped handle,
198 otherwise memory leaks or crashes will happen. This behaviour will
199 be fixed in the future.
200
201 curl_easy_pause
202 Not implemented.
203
204 curl_easy_reset
205 Not implemented.
206
207 curl_easy_unescape
208 Not implemented. Trivial Perl replacements are available.
209
210 curl_escape
211 Not implemented and won't be as this method is considered
212 deprecated.
213
214 curl_formadd
215 Seems to be working.
216
217 curl_formaddfile
218 Seems to be working.
219
220 curl_formfree
221 Used internally. Not exposed through the public API, as this call
222 has no relevance to Perl code.
223
224 curl_free
225 Used internally. Not exposed through the public API, as this call
226 has no relevance to Perl code.
227
228 curl_getdate
229 Not implemented. This function is easily replaced by Perl code and
230 as such, most likely it won't be implemented.
231
232 curl_global_cleanup
233 Only used internally, not exposed through the public API.
234
235 curl_global_init
236 Only used internally, not exposed through the public API.
237
238 curl_global_init_mem
239 Not implemented.
240
241 curl_global_cleanup
242 Only used internally and called automatically upon exit.
243
244 curl_slist_append
245 Only used internally, not exposed through the public API.
246
247 curl_slist_free_all
248 Only used internally, not exposed through the public API.
249
250 curl_unescape
251 Not implemented and won't be, as this method is considered
252 deprecated.
253
254 curl_version
255 Seems to work.
256
257 curl_version_info
258 Not yet implemented.
259
260 curl_multi_*
261 Most methods are either not exposed through the WWW::Curl::Multi
262 API or they behave differently than it's C counterpart. Please see
263 the section about WWW::Curl::Multi above.
264
265 curl_multi_fdset
266 This method returns three arrayrefs: the read, write and exception
267 fds libcurl knows about. In the case of no file descriptors in the
268 given set, an empty array is returned.
269
271 Header output for redirects
272 It might be surprising that if "CURLOPT_FOLLOWLOCATION" is set and
273 header output was enabled, headers show up for all http responses. The
274 reasoning behind that and possible code adjustments are outlined here:
275 <https://rt.cpan.org/Ticket/Display.html?id=61569>.
276
277 CURLOPT_PRIVATE
278 Despite what the libcurl manual says, in Perl land, only string values
279 are suitable for this option.
280
282 On WWW::Curl::Easy objects
283 pushopt
284 Like "setopt" but instead of overriding any previously set values
285 it adds it to the end. Can be used with "CURLOPT_HTTPHEADER",
286 "CURLOPT_QUOTE" and "CURLOPT_POSTQUOTE".
287
289 WWW::Curl is a thin binding on top of libcurl, to make using libcurl
290 possible from Perl land. Because of this, the module is less like Perl
291 and more like C in coding style.
292
293 There is a new module,
294 <http://search.cpan.org/perldoc?WWW::Curl::Simple>, which wraps this
295 module into a more Perlish and userfriendly package.
296
297 The standard Perl WWW module, LWP should probably be used in most cases
298 to work with HTTP or FTP from Perl. However, there are some cases
299 where LWP doesn't perform well. One is speed and the other is
300 parallelism. WWW::Curl is much faster, uses much less CPU cycles and
301 it's capable of non-blocking parallel requests.
302
303 In some cases, for example when building a web crawler, cpu usage and
304 parallel downloads are important considerations. It can be desirable to
305 use WWW::Curl to do the heavy-lifting of a large number of downloads
306 and wrap the resulting data into a Perl-friendly structure by
307 HTTP::Response or use WWW::Curl::Simple to do that for you.
308
310 Version 4.01 - 4.07 adds several bugfixes and extends functionality
311 coverage. See Changes file.
312
313 Version 4.00 added new documentation, the build system changed to
314 Module::Install, the test suite was rewritten to use Test::More, a new
315 calling syntax for WWW::Curl::Multi was added, memory leak and other
316 bugfixes added, Perl 5.6 and libcurl 7.10.8 as minimum requirements for
317 this module were set.
318
319 Version 3.12 is a bugfix for a missing Share.pm.in file in the release.
320
321 Version 3.11 added WWW::Curl::Share.
322
323 Version 3.10 adds the WWW::Curl::Share interface by Anton Federov and
324 large file options after a contribution from Mark Hindley.
325
326 Version 3.02 adds some backwards compatibility for scripts still using
327 'WWW::Curl::easy' names.
328
329 Version 3.01 added some support for pre-multi versions of libcurl.
330
331 Version 3.00 adds WWW::Curl::Multi interface, and new module names
332 following perl conventions (WWW::Curl::Easy rather than
333 WWW::Curl::easy), by Sebastian Riedel <sri at cpan.org>.
334
335 Version 2.00 of WWW::Curl::easy is a renaming of the previous version
336 (named Curl::easy), to follow CPAN naming guidelines, by Cris Bailiff.
337
338 Versions 1.30, a (hopefully) threadable, object-oriented, multiple-
339 callback compatible version of Curl::easy was substantially reworked
340 from the previous Curl::easy release (1.21) by Cris Bailiff.
341
343 Currently maintained by Cris Bailiff <c.bailiff+curl at devsecure.com>
344 and Balint Szilakszi <szbalint at cpan.org>.
345
346 Original Author Georg Horn <horn@koblenz-net.de>, with additional
347 callback, pod and test work by Cris Bailiff
348 <c.bailiff+curl@devsecure.com> and Forrest Cahoon
349 <forrest.cahoon@merrillcorp.com>. Sebastian Riedel added ::Multi and
350 Anton Fedorov (datacompboy <at> mail.ru) added ::Share. Balint
351 Szilakszi repackaged the module into a more modern form.
352
354 Copyright (C) 2000-2005,2008-2014 Daniel Stenberg, Cris Bailiff,
355 Sebastian Riedel, Balint Szilakszi et al.
356
357 You may opt to use, copy, modify, merge, publish, distribute and/or
358 sell copies of the Software, and permit persons to whom the Software is
359 furnished to do so, under the terms of the MIT license.
360
362 <http://curl.haxx.se>
363
364 <http://search.cpan.org/perldoc?WWW::Curl::Simple>
365
366 libcurl(3)
367
368 The development source code is also available:
369 <http://github.com/szbalint/WWW--Curl/tree/master>
370
371
372
373perl v5.32.1 2021-01-27 WWW::Curl(3)