Skip to content

Commit 2c136c1

Browse files
gislegisle
committed
pod2readme
1 parent b91925f commit 2c136c1

1 file changed

Lines changed: 233 additions & 90 deletions

File tree

‎README‎

Lines changed: 233 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,94 +1,237 @@
1-
2-
L I B W W W - P E R L - 5
3-
-----------------------------
4-
5-
6-
The libwww-perl collection is a set of Perl modules which provides a
7-
simple and consistent application programming interface to the
8-
World-Wide Web. The main focus of the library is to provide classes
9-
and functions that allow you to write WWW clients. The library also
10-
contain modules that are of more general use and even classes that
11-
help you implement simple HTTP servers.
12-
13-
14-
PREREQUISITES
15-
16-
In order to install and use this package you will need Perl version
17-
5.8.8 or better. Some modules within this package depend on other
18-
packages that are distributed separately from Perl. We recommend that
19-
you have the following packages installed before you install
20-
libwww-perl:
21-
22-
URI
23-
MIME-Base64
24-
HTML-Tagset
25-
HTML-Parser
26-
libnet
27-
Digest-MD5
28-
Encode-Locale
29-
Compress-Zlib
30-
31-
If you want to access sites using the https protocol, then you need to
32-
install the Crypt::SSLeay or the IO::Socket::SSL module. The
33-
README.SSL file will tell you more about how libwww-perl supports SSL.
34-
35-
36-
INSTALLATION
37-
38-
You install libwww-perl using the normal perl module distribution drill:
39-
40-
perl Makefile.PL
41-
make
42-
make test
43-
make install
44-
45-
If you don't want to install any programs (only the library files) then
46-
pass the '--no-programs' option to Makefile.PL:
47-
48-
perl Makefile.PL --no-programs
49-
50-
51-
DOCUMENTATION
52-
53-
See the lib/LWP.pm file for an overview of the library. See the
54-
Changes file for recent changes.
55-
56-
POD style documentation is included in all modules and scripts. These
57-
are normally converted to manual pages and installed as part of the
58-
"make install" process. You should also be able to use the 'perldoc'
59-
utility to extract and read documentation from the module files
60-
directly.
61-
62-
63-
SUPPORT
64-
65-
Bug reports and suggestions for improvements can be sent to the
66-
<libwww@perl.org> mailing list. This mailing list is also the place
67-
for general discussions and development of the libwww-perl package.
68-
69-
70-
AVAILABILITY
71-
72-
The latest version of libwww-perl is available from CPAN:
73-
74-
http://search.cpan.org/dist/libwww-perl/
75-
76-
If you want to hack on the source it might be a good idea to grab the
77-
latest version with git using the command:
78-
79-
git clone git://github.com/gisle/libwww-perl.git lwp
80-
81-
You can also browse the git repository at:
82-
83-
http://github.com/gisle/libwww-perl
84-
1+
NAME
2+
HTTP::Daemon - a simple http server class
3+
4+
SYNOPSIS
5+
use HTTP::Daemon;
6+
use HTTP::Status;
7+
8+
my $d = HTTP::Daemon->new || die;
9+
print "Please contact me at: <URL:", $d->url, ">\n";
10+
while (my $c = $d->accept) {
11+
while (my $r = $c->get_request) {
12+
if ($r->method eq 'GET' and $r->uri->path eq "/xyzzy") {
13+
# remember, this is *not* recommended practice :-)
14+
$c->send_file_response("/etc/passwd");
15+
}
16+
else {
17+
$c->send_error(RC_FORBIDDEN)
18+
}
19+
}
20+
$c->close;
21+
undef($c);
22+
}
23+
24+
DESCRIPTION
25+
Instances of the `HTTP::Daemon' class are HTTP/1.1 servers that listen
26+
on a socket for incoming requests. The `HTTP::Daemon' is a subclass of
27+
`IO::Socket::INET', so you can perform socket operations directly on it
28+
too.
29+
30+
The accept() method will return when a connection from a client is
31+
available. The returned value will be an `HTTP::Daemon::ClientConn'
32+
object which is another `IO::Socket::INET' subclass. Calling the
33+
get_request() method on this object will read data from the client and
34+
return an `HTTP::Request' object. The ClientConn object also provide
35+
methods to send back various responses.
36+
37+
This HTTP daemon does not fork(2) for you. Your application, i.e. the
38+
user of the `HTTP::Daemon' is responsible for forking if that is
39+
desirable. Also note that the user is responsible for generating
40+
responses that conform to the HTTP/1.1 protocol.
41+
42+
The following methods of `HTTP::Daemon' are new (or enhanced) relative
43+
to the `IO::Socket::INET' base class:
44+
45+
$d = HTTP::Daemon->new
46+
$d = HTTP::Daemon->new( %opts )
47+
The constructor method takes the same arguments as the
48+
`IO::Socket::INET' constructor, but unlike its base class it can
49+
also be called without any arguments. The daemon will then set up a
50+
listen queue of 5 connections and allocate some random port number.
51+
52+
A server that wants to bind to some specific address on the standard
53+
HTTP port will be constructed like this:
54+
55+
$d = HTTP::Daemon->new(
56+
LocalAddr => 'www.thisplace.com',
57+
LocalPort => 80,
58+
);
59+
60+
See IO::Socket::INET for a description of other arguments that can
61+
be used configure the daemon during construction.
62+
63+
$c = $d->accept
64+
$c = $d->accept( $pkg )
65+
($c, $peer_addr) = $d->accept
66+
This method works the same the one provided by the base class, but
67+
it returns an `HTTP::Daemon::ClientConn' reference by default. If a
68+
package name is provided as argument, then the returned object will
69+
be blessed into the given class. It is probably a good idea to make
70+
that class a subclass of `HTTP::Daemon::ClientConn'.
71+
72+
The accept method will return `undef' if timeouts have been enabled
73+
and no connection is made within the given time. The timeout()
74+
method is described in IO::Socket.
75+
76+
In list context both the client object and the peer address will be
77+
returned; see the description of the accept method IO::Socket for
78+
details.
79+
80+
$d->url
81+
Returns a URL string that can be used to access the server root.
82+
83+
$d->product_tokens
84+
Returns the name that this server will use to identify itself. This
85+
is the string that is sent with the `Server' response header. The
86+
main reason to have this method is that subclasses can override it
87+
if they want to use another product name.
88+
89+
The default is the string "libwww-perl-daemon/#.##" where "#.##" is
90+
replaced with the version number of this module.
91+
92+
The `HTTP::Daemon::ClientConn' is a `IO::Socket::INET' subclass.
93+
Instances of this class are returned by the accept() method of
94+
`HTTP::Daemon'. The following methods are provided:
95+
96+
$c->get_request
97+
$c->get_request( $headers_only )
98+
This method reads data from the client and turns it into an
99+
`HTTP::Request' object which is returned. It returns `undef' if
100+
reading fails. If it fails, then the `HTTP::Daemon::ClientConn'
101+
object ($c) should be discarded, and you should not try call this
102+
method again on it. The $c->reason method might give you some
103+
information about why $c->get_request failed.
104+
105+
The get_request() method will normally not return until the whole
106+
request has been received from the client. This might not be what
107+
you want if the request is an upload of a large file (and with
108+
chunked transfer encoding HTTP can even support infinite request
109+
messages - uploading live audio for instance). If you pass a TRUE
110+
value as the $headers_only argument, then get_request() will return
111+
immediately after parsing the request headers and you are
112+
responsible for reading the rest of the request content. If you are
113+
going to call $c->get_request again on the same connection you
114+
better read the correct number of bytes.
115+
116+
$c->read_buffer
117+
$c->read_buffer( $new_value )
118+
Bytes read by $c->get_request, but not used are placed in the *read
119+
buffer*. The next time $c->get_request is called it will consume the
120+
bytes in this buffer before reading more data from the network
121+
connection itself. The read buffer is invalid after $c->get_request
122+
has failed.
123+
124+
If you handle the reading of the request content yourself you need
125+
to empty this buffer before you read more and you need to place
126+
unconsumed bytes here. You also need this buffer if you implement
127+
services like *101 Switching Protocols*.
128+
129+
This method always returns the old buffer content and can optionally
130+
replace the buffer content if you pass it an argument.
131+
132+
$c->reason
133+
When $c->get_request returns `undef' you can obtain a short string
134+
describing why it happened by calling $c->reason.
135+
136+
$c->proto_ge( $proto )
137+
Return TRUE if the client announced a protocol with version number
138+
greater or equal to the given argument. The $proto argument can be a
139+
string like "HTTP/1.1" or just "1.1".
140+
141+
$c->antique_client
142+
Return TRUE if the client speaks the HTTP/0.9 protocol. No status
143+
code and no headers should be returned to such a client. This should
144+
be the same as !$c->proto_ge("HTTP/1.0").
145+
146+
$c->head_request
147+
Return TRUE if the last request was a `HEAD' request. No content
148+
body must be generated for these requests.
149+
150+
$c->force_last_request
151+
Make sure that $c->get_request will not try to read more requests
152+
off this connection. If you generate a response that is not self
153+
delimiting, then you should signal this fact by calling this method.
154+
155+
This attribute is turned on automatically if the client announces
156+
protocol HTTP/1.0 or worse and does not include a "Connection:
157+
Keep-Alive" header. It is also turned on automatically when HTTP/1.1
158+
or better clients send the "Connection: close" request header.
159+
160+
$c->send_status_line
161+
$c->send_status_line( $code )
162+
$c->send_status_line( $code, $mess )
163+
$c->send_status_line( $code, $mess, $proto )
164+
Send the status line back to the client. If $code is omitted 200 is
165+
assumed. If $mess is omitted, then a message corresponding to $code
166+
is inserted. If $proto is missing the content of the
167+
$HTTP::Daemon::PROTO variable is used.
168+
169+
$c->send_crlf
170+
Send the CRLF sequence to the client.
171+
172+
$c->send_basic_header
173+
$c->send_basic_header( $code )
174+
$c->send_basic_header( $code, $mess )
175+
$c->send_basic_header( $code, $mess, $proto )
176+
Send the status line and the "Date:" and "Server:" headers back to
177+
the client. This header is assumed to be continued and does not end
178+
with an empty CRLF line.
179+
180+
See the description of send_status_line() for the description of the
181+
accepted arguments.
182+
183+
$c->send_header( $field, $value )
184+
$c->send_header( $field1, $value1, $field2, $value2, ... )
185+
Send one or more header lines.
186+
187+
$c->send_response( $res )
188+
Write a `HTTP::Response' object to the client as a response. We try
189+
hard to make sure that the response is self delimiting so that the
190+
connection can stay persistent for further request/response
191+
exchanges.
192+
193+
The content attribute of the `HTTP::Response' object can be a normal
194+
string or a subroutine reference. If it is a subroutine, then
195+
whatever this callback routine returns is written back to the client
196+
as the response content. The routine will be called until it return
197+
an undefined or empty value. If the client is HTTP/1.1 aware then we
198+
will use chunked transfer encoding for the response.
199+
200+
$c->send_redirect( $loc )
201+
$c->send_redirect( $loc, $code )
202+
$c->send_redirect( $loc, $code, $entity_body )
203+
Send a redirect response back to the client. The location ($loc) can
204+
be an absolute or relative URL. The $code must be one the redirect
205+
status codes, and defaults to "301 Moved Permanently"
206+
207+
$c->send_error
208+
$c->send_error( $code )
209+
$c->send_error( $code, $error_message )
210+
Send an error response back to the client. If the $code is missing a
211+
"Bad Request" error is reported. The $error_message is a string that
212+
is incorporated in the body of the HTML entity body.
213+
214+
$c->send_file_response( $filename )
215+
Send back a response with the specified $filename as content. If the
216+
file is a directory we try to generate an HTML index of it.
217+
218+
$c->send_file( $filename )
219+
$c->send_file( $fd )
220+
Copy the file to the client. The file can be a string (which will be
221+
interpreted as a filename) or a reference to an `IO::Handle' or
222+
glob.
223+
224+
$c->daemon
225+
Return a reference to the corresponding `HTTP::Daemon' object.
226+
227+
SEE ALSO
228+
RFC 2616
229+
230+
IO::Socket::INET, IO::Socket
85231

86232
COPYRIGHT
233+
Copyright 1996-2003, Gisle Aas
87234

88-
© 1995-2010 Gisle Aas. All rights reserved.
89-
© 1995 Martijn Koster. All rights reserved.
90-
91-
This library is free software; you can redistribute it and/or modify
92-
it under the same terms as Perl itself.
235+
This library is free software; you can redistribute it and/or modify it
236+
under the same terms as Perl itself.
93237

94-
Enjoy!

0 commit comments

Comments
 (0)