1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. | will give a
29 .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30 .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "LWP::Simple 3"
132 .TH LWP::Simple 3 "2009-06-15" "perl v5.8.7" "User Contributed Perl Documentation"
134 LWP::Simple \- simple procedural interface to LWP
136 .IX Header "SYNOPSIS"
138 \& perl \-MLWP::Simple \-e 'getprint "http://www.sn.no"'
143 \& $content = get("http://www.sn.no/");
144 \& die "Couldn't get it!" unless defined $content;
148 \& if (mirror("http://www.sn.no/", "foo") == RC_NOT_MODIFIED) {
154 \& if (is_success(getprint("http://www.sn.no/"))) {
159 .IX Header "DESCRIPTION"
160 This module is meant for people who want a simplified view of the
161 libwww-perl library. It should also be suitable for one\-liners. If
162 you need more control or access to the header fields in the requests
163 sent and responses received, then you should use the full object-oriented
164 interface provided by the \f(CW\*(C`LWP::UserAgent\*(C'\fR module.
166 The following functions are provided (and exported) by this module:
169 The \fIget()\fR function will fetch the document identified by the given \s-1URL\s0
170 and return it. It returns \f(CW\*(C`undef\*(C'\fR if it fails. The \f(CW$url\fR argument can
171 be either a simple string or a reference to a \s-1URI\s0 object.
173 You will not be able to examine the response code or response headers
174 (like 'Content\-Type') when you are accessing the web using this
175 function. If you need that information you should use the full \s-1OO\s0
176 interface (see LWP::UserAgent).
178 .IX Item "head($url)"
179 Get document headers. Returns the following 5 values if successful:
180 ($content_type, \f(CW$document_length\fR, \f(CW$modified_time\fR, \f(CW$expires\fR, \f(CW$server\fR)
182 Returns an empty list if it fails. In scalar context returns \s-1TRUE\s0 if
184 .IP "getprint($url)" 3
185 .IX Item "getprint($url)"
186 Get and print a document identified by a \s-1URL\s0. The document is printed
187 to the selected default filehandle for output (normally \s-1STDOUT\s0) as
188 data is received from the network. If the request fails, then the
189 status code and message are printed on \s-1STDERR\s0. The return value is
190 the \s-1HTTP\s0 response code.
191 .ie n .IP "getstore($url, $file)" 3
192 .el .IP "getstore($url, \f(CW$file\fR)" 3
193 .IX Item "getstore($url, $file)"
194 Gets a document identified by a \s-1URL\s0 and stores it in the file. The
195 return value is the \s-1HTTP\s0 response code.
196 .ie n .IP "mirror($url, $file)" 3
197 .el .IP "mirror($url, \f(CW$file\fR)" 3
198 .IX Item "mirror($url, $file)"
199 Get and store a document identified by a \s-1URL\s0, using
200 \&\fIIf-modified-since\fR, and checking the \fIContent-Length\fR. Returns
201 the \s-1HTTP\s0 response code.
203 This module also exports the HTTP::Status constants and procedures.
204 You can use them when you check the response code from \fIgetprint()\fR,
205 \&\fIgetstore()\fR or \fImirror()\fR. The constants are:
209 \& RC_SWITCHING_PROTOCOLS
213 \& RC_NON_AUTHORITATIVE_INFORMATION
216 \& RC_PARTIAL_CONTENT
217 \& RC_MULTIPLE_CHOICES
218 \& RC_MOVED_PERMANENTLY
219 \& RC_MOVED_TEMPORARILY
225 \& RC_PAYMENT_REQUIRED
228 \& RC_METHOD_NOT_ALLOWED
230 \& RC_PROXY_AUTHENTICATION_REQUIRED
231 \& RC_REQUEST_TIMEOUT
234 \& RC_LENGTH_REQUIRED
235 \& RC_PRECONDITION_FAILED
236 \& RC_REQUEST_ENTITY_TOO_LARGE
237 \& RC_REQUEST_URI_TOO_LARGE
238 \& RC_UNSUPPORTED_MEDIA_TYPE
239 \& RC_INTERNAL_SERVER_ERROR
240 \& RC_NOT_IMPLEMENTED
242 \& RC_SERVICE_UNAVAILABLE
243 \& RC_GATEWAY_TIMEOUT
244 \& RC_HTTP_VERSION_NOT_SUPPORTED
247 The HTTP::Status classification functions are:
248 .IP "is_success($rc)" 3
249 .IX Item "is_success($rc)"
250 True if response code indicated a successful request.
251 .IP "is_error($rc)" 3
252 .IX Item "is_error($rc)"
253 True if response code indicated that an error occurred.
255 The module will also export the LWP::UserAgent object as \f(CW$ua\fR if you
256 ask for it explicitly.
258 The user agent created by this module will identify itself as
259 \&\*(L"LWP::Simple/#.##\*(R"
260 and will initialize its proxy defaults from the environment (by
261 calling \f(CW$ua\fR\->env_proxy).
264 Note that if you are using both LWP::Simple and the very popular \s-1CGI\s0.pm
265 module, you may be importing a \f(CW\*(C`head\*(C'\fR function from each module,
266 producing a warning like \*(L"Prototype mismatch: sub main::head ($) vs
267 none\*(R". Get around this problem by just not importing LWP::Simple's
268 \&\f(CW\*(C`head\*(C'\fR function, like so:
271 \& use LWP::Simple qw(!head);
272 \& use CGI qw(:standard); # then only CGI.pm defines a head()
275 Then if you do need LWP::Simple's \f(CW\*(C`head\*(C'\fR function, you can just call
276 it as \f(CW\*(C`LWP::Simple::head($url)\*(C'\fR.
278 .IX Header "SEE ALSO"
279 \&\s-1LWP\s0, lwpcook, LWP::UserAgent, HTTP::Status, lwp-request,