1LWP::UserAgent(3)     User Contributed Perl Documentation    LWP::UserAgent(3)
2
3
4

NAME

6       LWP::UserAgent - Web user agent class
7

SYNOPSIS

9           use strict;
10           use warnings;
11
12           use LWP::UserAgent ();
13
14           my $ua = LWP::UserAgent->new(timeout => 10);
15           $ua->env_proxy;
16
17           my $response = $ua->get('http://example.com');
18
19           if ($response->is_success) {
20               print $response->decoded_content;
21           }
22           else {
23               die $response->status_line;
24           }
25
26       Extra layers of security (note the "cookie_jar" and
27       "protocols_allowed"):
28
29           use strict;
30           use warnings;
31
32           use HTTP::CookieJar::LWP ();
33           use LWP::UserAgent       ();
34
35           my $jar = HTTP::CookieJar::LWP->new;
36           my $ua  = LWP::UserAgent->new(
37               cookie_jar        => $jar,
38               protocols_allowed => ['http', 'https'],
39               timeout           => 10,
40           );
41
42           $ua->env_proxy;
43
44           my $response = $ua->get('http://example.com');
45
46           if ($response->is_success) {
47               print $response->decoded_content;
48           }
49           else {
50               die $response->status_line;
51           }
52

DESCRIPTION

54       The LWP::UserAgent is a class implementing a web user agent.
55       LWP::UserAgent objects can be used to dispatch web requests.
56
57       In normal use the application creates an LWP::UserAgent object, and
58       then configures it with values for timeouts, proxies, name, etc. It
59       then creates an instance of HTTP::Request for the request that needs to
60       be performed. This request is then passed to one of the request method
61       the UserAgent, which dispatches it using the relevant protocol, and
62       returns a HTTP::Response object.  There are convenience methods for
63       sending the most common request types: "get" in LWP::UserAgent, "head"
64       in LWP::UserAgent, "post" in LWP::UserAgent, "put" in LWP::UserAgent
65       and "delete" in LWP::UserAgent.  When using these methods, the creation
66       of the request object is hidden as shown in the synopsis above.
67
68       The basic approach of the library is to use HTTP-style communication
69       for all protocol schemes.  This means that you will construct
70       HTTP::Request objects and receive HTTP::Response objects even for non-
71       HTTP resources like gopher and ftp.  In order to achieve even more
72       similarity to HTTP-style communications, gopher menus and file
73       directories are converted to HTML documents.
74

CONSTRUCTOR METHODS

76       The following constructor methods are available:
77
78   clone
79           my $ua2 = $ua->clone;
80
81       Returns a copy of the LWP::UserAgent object.
82
83       CAVEAT: Please be aware that the clone method does not copy or clone
84       your "cookie_jar" attribute. Due to the limited restrictions on what
85       can be used for your cookie jar, there is no way to clone the
86       attribute. The "cookie_jar" attribute will be "undef" in the new object
87       instance.
88
89   new
90           my $ua = LWP::UserAgent->new( %options )
91
92       This method constructs a new LWP::UserAgent object and returns it.
93       Key/value pair arguments may be provided to set up the initial state.
94       The following options correspond to attribute methods described below:
95
96          KEY                     DEFAULT
97          -----------             --------------------
98          agent                   "libwww-perl/#.###"
99          conn_cache              undef
100          cookie_jar              undef
101          default_headers         HTTP::Headers->new
102          from                    undef
103          local_address           undef
104          max_redirect            7
105          max_size                undef
106          no_proxy                []
107          parse_head              1
108          protocols_allowed       undef
109          protocols_forbidden     undef
110          proxy                   undef
111          requests_redirectable   ['GET', 'HEAD']
112          ssl_opts                { verify_hostname => 1 }
113          timeout                 180
114
115       The following additional options are also accepted: If the "env_proxy"
116       option is passed in with a true value, then proxy settings are read
117       from environment variables (see "env_proxy" in LWP::UserAgent). If
118       "env_proxy" isn't provided, the "PERL_LWP_ENV_PROXY" environment
119       variable controls if "env_proxy" in LWP::UserAgent is called during
120       initialization.  If the "keep_alive" option value is defined and non-
121       zero, then an "LWP::ConnCache" is set up (see "conn_cache" in
122       LWP::UserAgent).  The "keep_alive" value is passed on as the
123       "total_capacity" for the connection cache.
124
125       "proxy" must be set as an arrayref of key/value pairs. "no_proxy" takes
126       an arrayref of domains.
127

ATTRIBUTES

129       The settings of the configuration attributes modify the behaviour of
130       the LWP::UserAgent when it dispatches requests.  Most of these can also
131       be initialized by options passed to the constructor method.
132
133       The following attribute methods are provided.  The attribute value is
134       left unchanged if no argument is given.  The return value from each
135       method is the old attribute value.
136
137   agent
138           my $agent = $ua->agent;
139           $ua->agent('Checkbot/0.4 ');    # append the default to the end
140           $ua->agent('Mozilla/5.0');
141           $ua->agent("");                 # don't identify
142
143       Get/set the product token that is used to identify the user agent on
144       the network. The agent value is sent as the "User-Agent" header in the
145       requests.
146
147       The default is a string of the form "libwww-perl/#.###", where "#.###"
148       is substituted with the version number of this library.
149
150       If the provided string ends with space, the default "libwww-perl/#.###"
151       string is appended to it.
152
153       The user agent string should be one or more simple product identifiers
154       with an optional version number separated by the "/" character.
155
156   conn_cache
157           my $cache_obj = $ua->conn_cache;
158           $ua->conn_cache( $cache_obj );
159
160       Get/set the LWP::ConnCache object to use.  See LWP::ConnCache for
161       details.
162
163   cookie_jar
164           my $jar = $ua->cookie_jar;
165           $ua->cookie_jar( $cookie_jar_obj );
166
167       Get/set the cookie jar object to use.  The only requirement is that the
168       cookie jar object must implement the extract_cookies($response) and
169       add_cookie_header($request) methods.  These methods will then be
170       invoked by the user agent as requests are sent and responses are
171       received.  Normally this will be a HTTP::Cookies object or some
172       subclass.  You are, however, encouraged to use HTTP::CookieJar::LWP
173       instead.  See "BEST PRACTICES" for more information.
174
175           use HTTP::CookieJar::LWP ();
176
177           my $jar = HTTP::CookieJar::LWP->new;
178           my $ua = LWP::UserAgent->new( cookie_jar => $jar );
179
180           # or after object creation
181           $ua->cookie_jar( $cookie_jar );
182
183       The default is to have no cookie jar, i.e. never automatically add
184       "Cookie" headers to the requests.
185
186       Shortcut: If a reference to a plain hash is passed in, it is replaced
187       with an instance of HTTP::Cookies that is initialized based on the
188       hash. This form also automatically loads the HTTP::Cookies module.  It
189       means that:
190
191         $ua->cookie_jar({ file => "$ENV{HOME}/.cookies.txt" });
192
193       is really just a shortcut for:
194
195         require HTTP::Cookies;
196         $ua->cookie_jar(HTTP::Cookies->new(file => "$ENV{HOME}/.cookies.txt"));
197
198   credentials
199           my $creds = $ua->credentials();
200           $ua->credentials( $netloc, $realm );
201           $ua->credentials( $netloc, $realm, $uname, $pass );
202           $ua->credentials("www.example.com:80", "Some Realm", "foo", "secret");
203
204       Get/set the user name and password to be used for a realm.
205
206       The $netloc is a string of the form "<host>:<port>".  The username and
207       password will only be passed to this server.
208
209   default_header
210           $ua->default_header( $field );
211           $ua->default_header( $field => $value );
212           $ua->default_header('Accept-Encoding' => scalar HTTP::Message::decodable());
213           $ua->default_header('Accept-Language' => "no, en");
214
215       This is just a shortcut for "$ua->default_headers->header( $field =>
216       $value )".
217
218   default_headers
219           my $headers = $ua->default_headers;
220           $ua->default_headers( $headers_obj );
221
222       Get/set the headers object that will provide default header values for
223       any requests sent.  By default this will be an empty HTTP::Headers
224       object.
225
226   from
227           my $from = $ua->from;
228           $ua->from('foo@bar.com');
229
230       Get/set the email address for the human user who controls the
231       requesting user agent.  The address should be machine-usable, as
232       defined in RFC2822 <https://tools.ietf.org/html/rfc2822>. The "from"
233       value is sent as the "From" header in the requests.
234
235       The default is to not send a "From" header.  See "default_headers" in
236       LWP::UserAgent for the more general interface that allow any header to
237       be defaulted.
238
239   local_address
240           my $address = $ua->local_address;
241           $ua->local_address( $address );
242
243       Get/set the local interface to bind to for network connections.  The
244       interface can be specified as a hostname or an IP address.  This value
245       is passed as the "LocalAddr" argument to IO::Socket::INET.
246
247   max_redirect
248           my $max = $ua->max_redirect;
249           $ua->max_redirect( $n );
250
251       This reads or sets the object's limit of how many times it will obey
252       redirection responses in a given request cycle.
253
254       By default, the value is 7. This means that if you call "request" in
255       LWP::UserAgent and the response is a redirect elsewhere which is in
256       turn a redirect, and so on seven times, then LWP gives up after that
257       seventh request.
258
259   max_size
260           my $size = $ua->max_size;
261           $ua->max_size( $bytes );
262
263       Get/set the size limit for response content.  The default is "undef",
264       which means that there is no limit.  If the returned response content
265       is only partial, because the size limit was exceeded, then a
266       "Client-Aborted" header will be added to the response.  The content
267       might end up longer than "max_size" as we abort once appending a chunk
268       of data makes the length exceed the limit.  The "Content-Length"
269       header, if present, will indicate the length of the full content and
270       will normally not be the same as length($res->content).
271
272   parse_head
273           my $bool = $ua->parse_head;
274           $ua->parse_head( $boolean );
275
276       Get/set a value indicating whether we should initialize response
277       headers from the <head> section of HTML documents. The default is true.
278       Do not turn this off unless you know what you are doing.
279
280   protocols_allowed
281           my $aref = $ua->protocols_allowed;      # get allowed protocols
282           $ua->protocols_allowed( \@protocols );  # allow ONLY these
283           $ua->protocols_allowed(undef);          # delete the list
284           $ua->protocols_allowed(['http',]);      # ONLY allow http
285
286       By default, an object has neither a "protocols_allowed" list, nor a
287       "protocols_forbidden" in LWP::UserAgent list.
288
289       This reads (or sets) this user agent's list of protocols that the
290       request methods will exclusively allow.  The protocol names are case
291       insensitive.
292
293       For example: "$ua->protocols_allowed( [ 'http', 'https'] );" means that
294       this user agent will allow only those protocols, and attempts to use
295       this user agent to access URLs with any other schemes (like
296       "ftp://...") will result in a 500 error.
297
298       Note that having a "protocols_allowed" list causes any
299       "protocols_forbidden" in LWP::UserAgent list to be ignored.
300
301   protocols_forbidden
302           my $aref = $ua->protocols_forbidden;    # get the forbidden list
303           $ua->protocols_forbidden(\@protocols);  # do not allow these
304           $ua->protocols_forbidden(['http',]);    # All http reqs get a 500
305           $ua->protocols_forbidden(undef);        # delete the list
306
307       This reads (or sets) this user agent's list of protocols that the
308       request method will not allow. The protocol names are case insensitive.
309
310       For example: "$ua->protocols_forbidden( [ 'file', 'mailto'] );" means
311       that this user agent will not allow those protocols, and attempts to
312       use this user agent to access URLs with those schemes will result in a
313       500 error.
314
315   requests_redirectable
316           my $aref = $ua->requests_redirectable;
317           $ua->requests_redirectable( \@requests );
318           $ua->requests_redirectable(['GET', 'HEAD',]); # the default
319
320       This reads or sets the object's list of request names that
321       "redirect_ok" in LWP::UserAgent will allow redirection for. By default,
322       this is "['GET', 'HEAD']", as per RFC 2616
323       <https://tools.ietf.org/html/rfc2616>.  To change to include "POST",
324       consider:
325
326          push @{ $ua->requests_redirectable }, 'POST';
327
328   send_te
329           my $bool = $ua->send_te;
330           $ua->send_te( $boolean );
331
332       If true, will send a "TE" header along with the request. The default is
333       true. Set it to false to disable the "TE" header for systems who can't
334       handle it.
335
336   show_progress
337           my $bool = $ua->show_progress;
338           $ua->show_progress( $boolean );
339
340       Get/set a value indicating whether a progress bar should be displayed
341       on the terminal as requests are processed. The default is false.
342
343   ssl_opts
344           my @keys = $ua->ssl_opts;
345           my $val = $ua->ssl_opts( $key );
346           $ua->ssl_opts( $key => $value );
347
348       Get/set the options for SSL connections.  Without argument return the
349       list of options keys currently set.  With a single argument return the
350       current value for the given option.  With 2 arguments set the option
351       value and return the old.  Setting an option to the value "undef"
352       removes this option.
353
354       The options that LWP relates to are:
355
356       "verify_hostname" => $bool
357           When TRUE LWP will for secure protocol schemes ensure it connects
358           to servers that have a valid certificate matching the expected
359           hostname.  If FALSE no checks are made and you can't be sure that
360           you communicate with the expected peer.  The no checks behaviour
361           was the default for libwww-perl-5.837 and earlier releases.
362
363           This option is initialized from the "PERL_LWP_SSL_VERIFY_HOSTNAME"
364           environment variable.  If this environment variable isn't set; then
365           "verify_hostname" defaults to 1.
366
367       "SSL_ca_file" => $path
368           The path to a file containing Certificate Authority certificates.
369           A default setting for this option is provided by checking the
370           environment variables "PERL_LWP_SSL_CA_FILE" and "HTTPS_CA_FILE" in
371           order.
372
373       "SSL_ca_path" => $path
374           The path to a directory containing files containing Certificate
375           Authority certificates.  A default setting for this option is
376           provided by checking the environment variables
377           "PERL_LWP_SSL_CA_PATH" and "HTTPS_CA_DIR" in order.
378
379       Other options can be set and are processed directly by the SSL Socket
380       implementation in use.  See IO::Socket::SSL or Net::SSL for details.
381
382       The libwww-perl core no longer bundles protocol plugins for SSL.  You
383       will need to install LWP::Protocol::https separately to enable support
384       for processing https-URLs.
385
386   timeout
387           my $secs = $ua->timeout;
388           $ua->timeout( $secs );
389
390       Get/set the timeout value in seconds. The default value is 180 seconds,
391       i.e. 3 minutes.
392
393       The request is aborted if no activity on the connection to the server
394       is observed for "timeout" seconds.  This means that the time it takes
395       for the complete transaction and the "request" in LWP::UserAgent method
396       to actually return might be longer.
397
398       When a request times out, a response object is still returned.  The
399       response will have a standard HTTP Status Code (500).  This response
400       will have the "Client-Warning" header set to the value of "Internal
401       response".  See the "get" in LWP::UserAgent method description below
402       for further details.
403

PROXY ATTRIBUTES

405       The following methods set up when requests should be passed via a proxy
406       server.
407
408   env_proxy
409           $ua->env_proxy;
410
411       Load proxy settings from *_proxy environment variables.  You might
412       specify proxies like this (sh-syntax):
413
414         gopher_proxy=http://proxy.my.place/
415         wais_proxy=http://proxy.my.place/
416         no_proxy="localhost,example.com"
417         export gopher_proxy wais_proxy no_proxy
418
419       csh or tcsh users should use the "setenv" command to define these
420       environment variables.
421
422       On systems with case insensitive environment variables there exists a
423       name clash between the CGI environment variables and the "HTTP_PROXY"
424       environment variable normally picked up by "env_proxy".  Because of
425       this "HTTP_PROXY" is not honored for CGI scripts.  The "CGI_HTTP_PROXY"
426       environment variable can be used instead.
427
428   no_proxy
429           $ua->no_proxy( @domains );
430           $ua->no_proxy('localhost', 'example.com');
431           $ua->no_proxy(); # clear the list
432
433       Do not proxy requests to the given domains.  Calling "no_proxy" without
434       any domains clears the list of domains.
435
436   proxy
437           $ua->proxy(\@schemes, $proxy_url)
438           $ua->proxy(['http', 'ftp'], 'http://proxy.sn.no:8001/');
439
440           # For a single scheme:
441           $ua->proxy($scheme, $proxy_url)
442           $ua->proxy('gopher', 'http://proxy.sn.no:8001/');
443
444           # To set multiple proxies at once:
445           $ua->proxy([
446               ftp => 'http://ftp.example.com:8001/',
447               [ 'http', 'https' ] => 'http://http.example.com:8001/',
448           ]);
449
450       Set/retrieve proxy URL for a scheme.
451
452       The first form specifies that the URL is to be used as a proxy for
453       access methods listed in the list in the first method argument, i.e.
454       "http" and "ftp".
455
456       The second form shows a shorthand form for specifying proxy URL for a
457       single access scheme.
458
459       The third form demonstrates setting multiple proxies at once. This is
460       also the only form accepted by the constructor.
461

HANDLERS

463       Handlers are code that injected at various phases during the processing
464       of requests.  The following methods are provided to manage the active
465       handlers:
466
467   add_handler
468           $ua->add_handler( $phase => \&cb, %matchspec )
469
470       Add handler to be invoked in the given processing phase.  For how to
471       specify %matchspec see "Matching" in HTTP::Config.
472
473       The possible values $phase and the corresponding callback signatures
474       are as follows.  Note that the handlers are documented in the order in
475       which they will be run, which is:
476
477           request_preprepare
478           request_prepare
479           request_send
480           response_header
481           response_data
482           response_done
483           response_redirect
484
485       request_preprepare => sub { my($request, $ua, $handler) = @_; ... }
486           The handler is called before the "request_prepare" and other
487           standard initialization of the request.  This can be used to set up
488           headers and attributes that the "request_prepare" handler depends
489           on.  Proxy initialization should take place here; but in general
490           don't register handlers for this phase.
491
492       request_prepare => sub { my($request, $ua, $handler) = @_; ... }
493           The handler is called before the request is sent and can modify the
494           request any way it see fit.  This can for instance be used to add
495           certain headers to specific requests.
496
497           The method can assign a new request object to $_[0] to replace the
498           request that is sent fully.
499
500           The return value from the callback is ignored.  If an exception is
501           raised it will abort the request and make the request method return
502           a "400 Bad request" response.
503
504       request_send => sub { my($request, $ua, $handler) = @_; ... }
505           This handler gets a chance of handling requests before they're sent
506           to the protocol handlers.  It should return an HTTP::Response
507           object if it wishes to terminate the processing; otherwise it
508           should return nothing.
509
510           The "response_header" and "response_data" handlers will not be
511           invoked for this response, but the "response_done" will be.
512
513       response_header => sub { my($response, $ua, $handler) = @_; ... }
514           This handler is called right after the response headers have been
515           received, but before any content data.  The handler might set up
516           handlers for data and might croak to abort the request.
517
518           The handler might set the "$response->{default_add_content}" value
519           to control if any received data should be added to the response
520           object directly.  This will initially be false if the
521           "$ua->request()" method was called with a $content_file or
522           "$content_cb argument"; otherwise true.
523
524       response_data => sub { my($response, $ua, $handler, $data) = @_; ... }
525           This handler is called for each chunk of data received for the
526           response.  The handler might croak to abort the request.
527
528           This handler needs to return a TRUE value to be called again for
529           subsequent chunks for the same request.
530
531       response_done => sub { my($response, $ua, $handler) = @_; ... }
532           The handler is called after the response has been fully received,
533           but before any redirect handling is attempted.  The handler can be
534           used to extract information or modify the response.
535
536       response_redirect => sub { my($response, $ua, $handler) = @_; ... }
537           The handler is called in "$ua->request" after "response_done".  If
538           the handler returns an HTTP::Request object we'll start over with
539           processing this request instead.
540
541       For all of these, $handler is a code reference to the handler that is
542       currently being run.
543
544   get_my_handler
545           $ua->get_my_handler( $phase, %matchspec );
546           $ua->get_my_handler( $phase, %matchspec, $init );
547
548       Will retrieve the matching handler as hash ref.
549
550       If $init is passed as a true value, create and add the handler if it's
551       not found.  If $init is a subroutine reference, then it's called with
552       the created handler hash as argument.  This sub might populate the hash
553       with extra fields; especially the callback.  If $init is a hash
554       reference, merge the hashes.
555
556   handlers
557           $ua->handlers( $phase, $request )
558           $ua->handlers( $phase, $response )
559
560       Returns the handlers that apply to the given request or response at the
561       given processing phase.
562
563   remove_handler
564           $ua->remove_handler( undef, %matchspec );
565           $ua->remove_handler( $phase, %matchspec );
566           $ua->remove_handler(); # REMOVE ALL HANDLERS IN ALL PHASES
567
568       Remove handlers that match the given %matchspec.  If $phase is not
569       provided, remove handlers from all phases.
570
571       Be careful as calling this function with %matchspec that is not
572       specific enough can remove handlers not owned by you.  It's probably
573       better to use the "set_my_handler" in LWP::UserAgent method instead.
574
575       The removed handlers are returned.
576
577   set_my_handler
578           $ua->set_my_handler( $phase, $cb, %matchspec );
579           $ua->set_my_handler($phase, undef); # remove handler for phase
580
581       Set handlers private to the executing subroutine.  Works by defaulting
582       an "owner" field to the %matchspec that holds the name of the called
583       subroutine.  You might pass an explicit "owner" to override this.
584
585       If $cb is passed as "undef", remove the handler.
586

REQUEST METHODS

588       The methods described in this section are used to dispatch requests via
589       the user agent.  The following request methods are provided:
590
591   delete
592           my $res = $ua->delete( $url );
593           my $res = $ua->delete( $url, $field_name => $value, ... );
594
595       This method will dispatch a "DELETE" request on the given URL.
596       Additional headers and content options are the same as for the "get" in
597       LWP::UserAgent method.
598
599       This method will use the DELETE() function from HTTP::Request::Common
600       to build the request.  See HTTP::Request::Common for a details on how
601       to pass form content and other advanced features.
602
603   get
604           my $res = $ua->get( $url );
605           my $res = $ua->get( $url , $field_name => $value, ... );
606
607       This method will dispatch a "GET" request on the given URL.  Further
608       arguments can be given to initialize the headers of the request. These
609       are given as separate name/value pairs.  The return value is a response
610       object.  See HTTP::Response for a description of the interface it
611       provides.
612
613       There will still be a response object returned when LWP can't connect
614       to the server specified in the URL or when other failures in protocol
615       handlers occur.  These internal responses use the standard HTTP status
616       codes, so the responses can't be differentiated by testing the response
617       status code alone.  Error responses that LWP generates internally will
618       have the "Client-Warning" header set to the value "Internal response".
619       If you need to differentiate these internal responses from responses
620       that a remote server actually generates, you need to test this header
621       value.
622
623       Fields names that start with ":" are special.  These will not
624       initialize headers of the request but will determine how the response
625       content is treated.  The following special field names are recognized:
626
627           ':content_file'   => $filename # or $filehandle
628           ':content_cb'     => \&callback
629           ':read_size_hint' => $bytes
630
631       If a $filename or $filehandle is provided with the ":content_file"
632       option, then the response content will be saved here instead of in the
633       response object.  The $filehandle may also be an object with an open
634       file descriptor, such as a File::Temp object.  If a callback is
635       provided with the ":content_cb" option then this function will be
636       called for each chunk of the response content as it is received from
637       the server.  If neither of these options are given, then the response
638       content will accumulate in the response object itself.  This might not
639       be suitable for very large response bodies.  Only one of
640       ":content_file" or ":content_cb" can be specified.  The content of
641       unsuccessful responses will always accumulate in the response object
642       itself, regardless of the ":content_file" or ":content_cb" options
643       passed in.  Note that errors writing to the content file (for example
644       due to permission denied or the filesystem being full) will be reported
645       via the "Client-Aborted" or "X-Died" response headers, and not the
646       "is_success" method.
647
648       The ":read_size_hint" option is passed to the protocol module which
649       will try to read data from the server in chunks of this size.  A
650       smaller value for the ":read_size_hint" will result in a higher number
651       of callback invocations.
652
653       The callback function is called with 3 arguments: a chunk of data, a
654       reference to the response object, and a reference to the protocol
655       object.  The callback can abort the request by invoking die().  The
656       exception message will show up as the "X-Died" header field in the
657       response returned by the "$ua->get()" method.
658
659   head
660           my $res = $ua->head( $url );
661           my $res = $ua->head( $url , $field_name => $value, ... );
662
663       This method will dispatch a "HEAD" request on the given URL.  Otherwise
664       it works like the "get" in LWP::UserAgent method described above.
665
666   is_protocol_supported
667           my $bool = $ua->is_protocol_supported( $scheme );
668
669       You can use this method to test whether this user agent object supports
670       the specified "scheme".  (The "scheme" might be a string (like "http"
671       or "ftp") or it might be an URI object reference.)
672
673       Whether a scheme is supported is determined by the user agent's
674       "protocols_allowed" or "protocols_forbidden" lists (if any), and by the
675       capabilities of LWP.  I.e., this will return true only if LWP supports
676       this protocol and it's permitted for this particular object.
677
678   is_online
679           my $bool = $ua->is_online;
680
681       Tries to determine if you have access to the Internet. Returns 1 (true)
682       if the built-in heuristics determine that the user agent is able to
683       access the Internet (over HTTP) or 0 (false).
684
685       See also LWP::Online.
686
687   mirror
688           my $res = $ua->mirror( $url, $filename );
689
690       This method will get the document identified by URL and store it in
691       file called $filename.  If the file already exists, then the request
692       will contain an "If-Modified-Since" header matching the modification
693       time of the file.  If the document on the server has not changed since
694       this time, then nothing happens.  If the document has been updated, it
695       will be downloaded again.  The modification time of the file will be
696       forced to match that of the server.
697
698       Uses "move" in File::Copy to attempt to atomically replace the
699       $filename.
700
701       The return value is an HTTP::Response object.
702
703   patch
704           # Any version of HTTP::Message works with this form:
705           my $res = $ua->patch( $url, $field_name => $value, Content => $content );
706
707           # Using hash or array references requires HTTP::Message >= 6.12
708           use HTTP::Request 6.12;
709           my $res = $ua->patch( $url, \%form );
710           my $res = $ua->patch( $url, \@form );
711           my $res = $ua->patch( $url, \%form, $field_name => $value, ... );
712           my $res = $ua->patch( $url, $field_name => $value, Content => \%form );
713           my $res = $ua->patch( $url, $field_name => $value, Content => \@form );
714
715       This method will dispatch a "PATCH" request on the given URL, with
716       %form or @form providing the key/value pairs for the fill-in form
717       content. Additional headers and content options are the same as for the
718       "get" in LWP::UserAgent method.
719
720       CAVEAT:
721
722       This method can only accept content that is in key-value pairs when
723       using HTTP::Request::Common prior to version 6.12. Any use of hash or
724       array references will result in an error prior to version 6.12.
725
726       This method will use the "PATCH" function from HTTP::Request::Common to
727       build the request.  See HTTP::Request::Common for a details on how to
728       pass form content and other advanced features.
729
730   post
731           my $res = $ua->post( $url, \%form );
732           my $res = $ua->post( $url, \@form );
733           my $res = $ua->post( $url, \%form, $field_name => $value, ... );
734           my $res = $ua->post( $url, $field_name => $value, Content => \%form );
735           my $res = $ua->post( $url, $field_name => $value, Content => \@form );
736           my $res = $ua->post( $url, $field_name => $value, Content => $content );
737
738       This method will dispatch a "POST" request on the given URL, with %form
739       or @form providing the key/value pairs for the fill-in form content.
740       Additional headers and content options are the same as for the "get" in
741       LWP::UserAgent method.
742
743       This method will use the "POST" function from HTTP::Request::Common to
744       build the request.  See HTTP::Request::Common for a details on how to
745       pass form content and other advanced features.
746
747   put
748           # Any version of HTTP::Message works with this form:
749           my $res = $ua->put( $url, $field_name => $value, Content => $content );
750
751           # Using hash or array references requires HTTP::Message >= 6.07
752           use HTTP::Request 6.07;
753           my $res = $ua->put( $url, \%form );
754           my $res = $ua->put( $url, \@form );
755           my $res = $ua->put( $url, \%form, $field_name => $value, ... );
756           my $res = $ua->put( $url, $field_name => $value, Content => \%form );
757           my $res = $ua->put( $url, $field_name => $value, Content => \@form );
758
759       This method will dispatch a "PUT" request on the given URL, with %form
760       or @form providing the key/value pairs for the fill-in form content.
761       Additional headers and content options are the same as for the "get" in
762       LWP::UserAgent method.
763
764       CAVEAT:
765
766       This method can only accept content that is in key-value pairs when
767       using HTTP::Request::Common prior to version 6.07. Any use of hash or
768       array references will result in an error prior to version 6.07.
769
770       This method will use the "PUT" function from HTTP::Request::Common to
771       build the request.  See HTTP::Request::Common for a details on how to
772       pass form content and other advanced features.
773
774   request
775           my $res = $ua->request( $request );
776           my $res = $ua->request( $request, $content_file );
777           my $res = $ua->request( $request, $content_cb );
778           my $res = $ua->request( $request, $content_cb, $read_size_hint );
779
780       This method will dispatch the given $request object. Normally this will
781       be an instance of the HTTP::Request class, but any object with a
782       similar interface will do. The return value is an HTTP::Response
783       object.
784
785       The "request" method will process redirects and authentication
786       responses transparently. This means that it may actually send several
787       simple requests via the "simple_request" in LWP::UserAgent method
788       described below.
789
790       The request methods described above; "get" in LWP::UserAgent, "head" in
791       LWP::UserAgent, "post" in LWP::UserAgent and "mirror" in LWP::UserAgent
792       will all dispatch the request they build via this method. They are
793       convenience methods that simply hide the creation of the request object
794       for you.
795
796       The $content_file, $content_cb and $read_size_hint all correspond to
797       options described with the "get" in LWP::UserAgent method above. Note
798       that errors writing to the content file (for example due to permission
799       denied or the filesystem being full) will be reported via the
800       "Client-Aborted" or "X-Died" response headers, and not the "is_success"
801       method.
802
803       You are allowed to use a CODE reference as "content" in the request
804       object passed in.  The "content" function should return the content
805       when called.  The content can be returned in chunks.  The content
806       function will be invoked repeatedly until it return an empty string to
807       signal that there is no more content.
808
809   simple_request
810           my $request = HTTP::Request->new( ... );
811           my $res = $ua->simple_request( $request );
812           my $res = $ua->simple_request( $request, $content_file );
813           my $res = $ua->simple_request( $request, $content_cb );
814           my $res = $ua->simple_request( $request, $content_cb, $read_size_hint );
815
816       This method dispatches a single request and returns the response
817       received.  Arguments are the same as for the "request" in
818       LWP::UserAgent described above.
819
820       The difference from "request" in LWP::UserAgent is that
821       "simple_request" will not try to handle redirects or authentication
822       responses.  The "request" in LWP::UserAgent method will, in fact,
823       invoke this method for each simple request it sends.
824

CALLBACK METHODS

826       The following methods will be invoked as requests are processed. These
827       methods are documented here because subclasses of LWP::UserAgent might
828       want to override their behaviour.
829
830   get_basic_credentials
831           # This checks wantarray and can either return an array:
832           my ($user, $pass) = $ua->get_basic_credentials( $realm, $uri, $isproxy );
833           # or a string that looks like "user:pass"
834           my $creds = $ua->get_basic_credentials($realm, $uri, $isproxy);
835
836       This is called by "request" in LWP::UserAgent to retrieve credentials
837       for documents protected by Basic or Digest Authentication.  The
838       arguments passed in is the $realm provided by the server, the $uri
839       requested and a "boolean flag" to indicate if this is authentication
840       against a proxy server.
841
842       The method should return a username and password.  It should return an
843       empty list to abort the authentication resolution attempt.  Subclasses
844       can override this method to prompt the user for the information. An
845       example of this can be found in "lwp-request" program distributed with
846       this library.
847
848       The base implementation simply checks a set of pre-stored member
849       variables, set up with the "credentials" in LWP::UserAgent method.
850
851   prepare_request
852           $request = $ua->prepare_request( $request );
853
854       This method is invoked by "simple_request" in LWP::UserAgent. Its task
855       is to modify the given $request object by setting up various headers
856       based on the attributes of the user agent. The return value should
857       normally be the $request object passed in.  If a different request
858       object is returned it will be the one actually processed.
859
860       The headers affected by the base implementation are; "User-Agent",
861       "From", "Range" and "Cookie".
862
863   progress
864           my $prog = $ua->progress( $status, $request_or_response );
865
866       This is called frequently as the response is received regardless of how
867       the content is processed.  The method is called with $status "begin" at
868       the start of processing the request and with $state "end" before the
869       request method returns.  In between these $status will be the fraction
870       of the response currently received or the string "tick" if the fraction
871       can't be calculated.
872
873       When $status is "begin" the second argument is the HTTP::Request
874       object, otherwise it is the HTTP::Response object.
875
876   redirect_ok
877           my $bool = $ua->redirect_ok( $prospective_request, $response );
878
879       This method is called by "request" in LWP::UserAgent before it tries to
880       follow a redirection to the request in $response.  This should return a
881       true value if this redirection is permissible.  The
882       $prospective_request will be the request to be sent if this method
883       returns true.
884
885       The base implementation will return false unless the method is in the
886       object's "requests_redirectable" list, false if the proposed
887       redirection is to a "file://..."  URL, and true otherwise.
888

BEST PRACTICES

890       The default settings can get you up and running quickly, but there are
891       settings you can change in order to make your life easier.
892
893   Handling Cookies
894       You are encouraged to install Mozilla::PublicSuffix and use
895       HTTP::CookieJar::LWP as your cookie jar.  HTTP::CookieJar::LWP provides
896       a better security model matching that of current Web browsers when
897       Mozilla::PublicSuffix is installed.
898
899           use HTTP::CookieJar::LWP ();
900
901           my $jar = HTTP::CookieJar::LWP->new;
902           my $ua = LWP::UserAgent->new( cookie_jar => $jar );
903
904       See "cookie_jar" for more information.
905
906   Managing Protocols
907       "protocols_allowed" gives you the ability to allow arbitrary protocols.
908
909           my $ua = LWP::UserAgent->new(
910               protocols_allowed => [ 'http', 'https' ]
911           );
912
913       This will prevent you from inadvertently following URLs like
914       "file:///etc/passwd".  See "protocols_allowed".
915
916       "protocols_forbidden" gives you the ability to deny arbitrary
917       protocols.
918
919           my $ua = LWP::UserAgent->new(
920               protocols_forbidden => [ 'file', 'mailto', 'ssh', ]
921           );
922
923       This can also prevent you from inadvertently following URLs like
924       "file:///etc/passwd".  See "protocols_forbidden".
925

SEE ALSO

927       See LWP for a complete overview of libwww-perl5.  See lwpcook and the
928       scripts lwp-request and lwp-download for examples of usage.
929
930       See HTTP::Request and HTTP::Response for a description of the message
931       objects dispatched and received.  See HTTP::Request::Common and
932       HTML::Form for other ways to build request objects.
933
934       See WWW::Mechanize and WWW::Search for examples of more specialized
935       user agents based on LWP::UserAgent.
936
938       Copyright 1995-2009 Gisle Aas.
939
940       This library is free software; you can redistribute it and/or modify it
941       under the same terms as Perl itself.
942
943
944
945perl v5.36.0                      2023-03-01                 LWP::UserAgent(3)
Impressum