1HTTP::Daemon(3)       User Contributed Perl Documentation      HTTP::Daemon(3)
2
3
4

NAME

6       HTTP::Daemon - A simple http server class
7

VERSION

9       version 6.14
10

SYNOPSIS

12         use HTTP::Daemon;
13         use HTTP::Status;
14
15         my $d = HTTP::Daemon->new || die;
16         print "Please contact me at: <URL:", $d->url, ">\n";
17         while (my $c = $d->accept) {
18             while (my $r = $c->get_request) {
19             if ($r->method eq 'GET' and $r->uri->path eq "/xyzzy") {
20                     # remember, this is *not* recommended practice :-)
21                 $c->send_file_response("/etc/passwd");
22             }
23             else {
24                 $c->send_error(RC_FORBIDDEN)
25             }
26             }
27             $c->close;
28             undef($c);
29         }
30

DESCRIPTION

32       Instances of the "HTTP::Daemon" class are HTTP/1.1 servers that listen
33       on a socket for incoming requests. The "HTTP::Daemon" is a subclass of
34       "IO::Socket::IP", so you can perform socket operations directly on it
35       too.
36
37       Please note that "HTTP::Daemon" used to be a subclass of
38       "IO::Socket::INET".  To support IPv6, it switched the parent class to
39       "IO::Socket::IP" at version 6.05.  See "IPv6 SUPPORT" for details.
40
41       The accept() method will return when a connection from a client is
42       available.  The returned value will be an "HTTP::Daemon::ClientConn"
43       object which is another "IO::Socket::IP" subclass.  Calling the
44       get_request() method on this object will read data from the client and
45       return an "HTTP::Request" object.  The ClientConn object also provide
46       methods to send back various responses.
47
48       This HTTP daemon does not fork(2) for you.  Your application, i.e. the
49       user of the "HTTP::Daemon" is responsible for forking if that is
50       desirable.  Also note that the user is responsible for generating
51       responses that conform to the HTTP/1.1 protocol.
52
53       The following methods of "HTTP::Daemon" are new (or enhanced) relative
54       to the "IO::Socket::IP" base class:
55
56       $d = HTTP::Daemon->new
57       $d = HTTP::Daemon->new( %opts )
58           The constructor method takes the same arguments as the
59           "IO::Socket::IP" constructor, but unlike its base class it can also
60           be called without any arguments.  The daemon will then set up a
61           listen queue of 5 connections and allocate some random port number.
62
63           A server that wants to bind to some specific address on the
64           standard HTTP port will be constructed like this:
65
66             $d = HTTP::Daemon->new(
67                      LocalAddr => 'www.thisplace.com',
68                      LocalPort => 80,
69                  );
70
71           See IO::Socket::IP for a description of other arguments that can be
72           used to configure the daemon during construction.
73
74       $c = $d->accept
75       $c = $d->accept( $pkg )
76       ($c, $peer_addr) = $d->accept
77           This method works the same as the one provided by the base class,
78           but it returns an "HTTP::Daemon::ClientConn" reference by default.
79           If a package name is provided as argument, then the returned object
80           will be blessed into the given class.  It is probably a good idea
81           to make that class a subclass of "HTTP::Daemon::ClientConn".
82
83           The accept method will return "undef" if timeouts have been enabled
84           and no connection is made within the given time.  The timeout()
85           method is described in IO::Socket::IP.
86
87           In list context both the client object and the peer address will be
88           returned; see the description of the accept method of IO::Socket
89           for details.
90
91       $d->url
92           Returns a URL string that can be used to access the server root.
93
94       $d->product_tokens
95           Returns the name that this server will use to identify itself.
96           This is the string that is sent with the "Server" response header.
97           The main reason to have this method is that subclasses can override
98           it if they want to use another product name.
99
100           The default is the string "libwww-perl-daemon/#.##" where "#.##" is
101           replaced with the version number of this module.
102
103       The "HTTP::Daemon::ClientConn" is a subclass of "IO::Socket::IP".
104       Instances of this class are returned by the accept() method of
105       "HTTP::Daemon".  The following methods are provided:
106
107       $c->get_request
108       $c->get_request( $headers_only )
109           This method reads data from the client and turns it into an
110           "HTTP::Request" object which is returned.  It returns "undef" if
111           reading fails.  If it fails, then the "HTTP::Daemon::ClientConn"
112           object ($c) should be discarded, and you should not try to call
113           this method again on it.  The $c->reason method might give you some
114           information about why $c->get_request failed.
115
116           The get_request() method will normally not return until the whole
117           request has been received from the client.  This might not be what
118           you want if the request is an upload of a large file (and with
119           chunked transfer encoding HTTP can even support infinite request
120           messages - uploading live audio for instance).  If you pass a TRUE
121           value as the $headers_only argument, then get_request() will return
122           immediately after parsing the request headers and you are
123           responsible for reading the rest of the request content.  If you
124           are going to call $c->get_request again on the same connection you
125           better read the correct number of bytes.
126
127       $c->read_buffer
128       $c->read_buffer( $new_value )
129           Bytes read by $c->get_request, but not used are placed in the read
130           buffer.  The next time $c->get_request is called it will consume
131           the bytes in this buffer before reading more data from the network
132           connection itself.  The read buffer is invalid after
133           $c->get_request has failed.
134
135           If you handle the reading of the request content yourself you need
136           to empty this buffer before you read more and you need to place
137           unconsumed bytes here.  You also need this buffer if you implement
138           services like 101 Switching Protocols.
139
140           This method always returns the old buffer content and can
141           optionally replace the buffer content if you pass it an argument.
142
143       $c->reason
144           When $c->get_request returns "undef" you can obtain a short string
145           describing why it happened by calling $c->reason.
146
147       $c->proto_ge( $proto )
148           Return TRUE if the client announced a protocol with version number
149           greater or equal to the given argument.  The $proto argument can be
150           a string like "HTTP/1.1" or just "1.1".
151
152       $c->antique_client
153           Return TRUE if the client speaks the HTTP/0.9 protocol.  No status
154           code and no headers should be returned to such a client.  This
155           should be the same as !$c->proto_ge("HTTP/1.0").
156
157       $c->head_request
158           Return TRUE if the last request was a "HEAD" request.  No content
159           body must be generated for these requests.
160
161       $c->force_last_request
162           Make sure that $c->get_request will not try to read more requests
163           off this connection.  If you generate a response that is not self-
164           delimiting, then you should signal this fact by calling this
165           method.
166
167           This attribute is turned on automatically if the client announces
168           protocol HTTP/1.0 or worse and does not include a "Connection:
169           Keep-Alive" header.  It is also turned on automatically when
170           HTTP/1.1 or better clients send the "Connection: close" request
171           header.
172
173       $c->send_status_line
174       $c->send_status_line( $code )
175       $c->send_status_line( $code, $mess )
176       $c->send_status_line( $code, $mess, $proto )
177           Send the status line back to the client.  If $code is omitted 200
178           is assumed.  If $mess is omitted, then a message corresponding to
179           $code is inserted.  If $proto is missing the content of the
180           $HTTP::Daemon::PROTO variable is used.
181
182       $c->send_crlf
183           Send the CRLF sequence to the client.
184
185       $c->send_basic_header
186       $c->send_basic_header( $code )
187       $c->send_basic_header( $code, $mess )
188       $c->send_basic_header( $code, $mess, $proto )
189           Send the status line and the "Date:" and "Server:" headers back to
190           the client.  This header is assumed to be continued and does not
191           end with an empty CRLF line.
192
193           See the description of send_status_line() for the description of
194           the accepted arguments.
195
196       $c->send_header( $field, $value )
197       $c->send_header( $field1, $value1, $field2, $value2, ... )
198           Send one or more header lines.
199
200       $c->send_response( $res )
201           Write an "HTTP::Response" object to the client as a response.  We
202           try hard to make sure that the response is self-delimiting so that
203           the connection can stay persistent for further request/response
204           exchanges.
205
206           The content attribute of the "HTTP::Response" object can be a
207           normal string or a subroutine reference.  If it is a subroutine,
208           then whatever this callback routine returns is written back to the
209           client as the response content.  The routine will be called until
210           it returns an undefined or empty value.  If the client is HTTP/1.1
211           aware then we will use chunked transfer encoding for the response.
212
213       $c->send_redirect( $loc )
214       $c->send_redirect( $loc, $code )
215       $c->send_redirect( $loc, $code, $entity_body )
216           Send a redirect response back to the client.  The location ($loc)
217           can be an absolute or relative URL. The $code must be one of the
218           redirect status codes, and defaults to "301 Moved Permanently"
219
220       $c->send_error
221       $c->send_error( $code )
222       $c->send_error( $code, $error_message )
223           Send an error response back to the client.  If the $code is missing
224           a "Bad Request" error is reported.  The $error_message is a string
225           that is incorporated in the body of the HTML entity.
226
227       $c->send_file_response( $filename )
228           Send back a response with the specified $filename as content.  If
229           the file is a directory we try to generate an HTML index of it.
230
231       $c->send_file( $filename )
232       $c->send_file( $fd )
233           Copy the file to the client.  The file can be a string (which will
234           be interpreted as a filename) or a reference to an "IO::Handle" or
235           glob.
236
237       $c->daemon
238           Return a reference to the corresponding "HTTP::Daemon" object.
239

IPv6 SUPPORT

241       Since version 6.05, "HTTP::Daemon" is a subclass of "IO::Socket::IP"
242       rather than "IO::Socket::INET", so that it supports IPv6.
243
244       For some reasons, you may want to force "HTTP::Daemon" to listen on
245       IPv4 addresses only.  Then pass "Family" argument to
246       "HTTP::Daemon->new":
247
248         use HTTP::Daemon;
249         use Socket 'AF_INET';
250
251         my $d = HTTP::Daemon->new(Family => AF_INET);
252

SEE ALSO

254       RFC 2616
255
256       IO::Socket::IP, IO::Socket
257

SUPPORT

259       Bugs may be submitted through
260       <https://github.com/libwww-perl/HTTP-Daemon/issues>.
261
262       There is also a mailing list available for users of this distribution,
263       at <mailto:libwww@perl.org>.
264
265       There is also an irc channel available for users of this distribution,
266       at "#lwp" on "irc.perl.org" <irc://irc.perl.org/#lwp>.
267

AUTHOR

269       Gisle Aas <gisle@activestate.com>
270

CONTRIBUTORS

272       •   Olaf Alders <olaf@wundersolutions.com>
273
274       •   Ville Skyttä <ville.skytta@iki.fi>
275
276       •   Karen Etheridge <ether@cpan.org>
277
278       •   Mark Stosberg <MARKSTOS@cpan.org>
279
280       •   Shoichi Kaji <skaji@cpan.org>
281
282       •   Chase Whitener <capoeirab@cpan.org>
283
284       •   Slaven Rezic <slaven@rezic.de>
285
286       •   Petr Písař <ppisar@redhat.com>
287
288       •   Zefram <zefram@fysh.org>
289
290       •   Alexey Tourbin <at@altlinux.ru>
291
292       •   Bron Gondwana <brong@fastmail.fm>
293
294       •   Michal Josef Špaček <mspacek@redhat.com>
295
296       •   Mike Schilli <mschilli@yahoo-inc.com>
297
298       •   Tom Hukins <tom@eborcom.com>
299
300       •   Adam Kennedy <adamk@cpan.org>
301
302       •   Adam Sjogren <asjo@koldfront.dk>
303
304       •   Alex Kapranoff <ka@nadoby.ru>
305
306       •   amire80 <amir.aharoni@gmail.com>
307
308       •   Andreas J. Koenig <andreas.koenig@anima.de>
309
310       •   Bill Mann <wfmann@alum.mit.edu>
311
312       •   Daniel Hedlund <Daniel.Hedlund@eprize.com>
313
314       •   David E. Wheeler <david@justatheory.com>
315
316       •   DAVIDRW <davidrw@cpan.org>
317
318       •   Father Chrysostomos <sprout@cpan.org>
319
320       •   Ferenc Erki <erkiferenc@gmail.com>
321
322       •   FWILES <FWILES@cpan.org>
323
324       •   Gavin Peters <gpeters@deepsky.com>
325
326       •   Graeme Thompson <Graeme.Thompson@mobilecohesion.com>
327
328       •   Hans-H. Froehlich <hfroehlich@co-de-co.de>
329
330       •   Ian Kilgore <iank@cpan.org>
331
332       •   Jacob J <waif@chaos2.org>
333
334       •   jefflee <shaohua@gmail.com>
335
336       •   john9art <john9art@yahoo.com>
337
338       •   murphy <murphy@genome.chop.edu>
339
340       •   Ondrej Hanak <ondrej.hanak@ubs.com>
341
342       •   Perlover <perlover@perlover.com>
343
344       •   Peter Rabbitson <ribasushi@cpan.org>
345
346       •   phrstbrn <phrstbrn@gmail.com>
347
348       •   Robert Stone <talby@trap.mtview.ca.us>
349
350       •   Rolf Grossmann <rg@progtech.net>
351
352       •   ruff <ruff@ukrpost.net>
353
354       •   sasao <sasao@yugen.org>
355
356       •   Sean M. Burke <sburke@cpan.org>
357
358       •   Spiros Denaxas <s.denaxas@gmail.com>
359
360       •   Steve Hay <SteveHay@planit.com>
361
362       •   Todd Lipcon <todd@amiestreet.com>
363
364       •   Tony Finch <dot@dotat.at>
365
366       •   Toru Yamaguchi <zigorou@cpan.org>
367
368       •   Yuri Karaban <tech@askold.net>
369
371       This software is copyright (c) 1995 by Gisle Aas.
372
373       This is free software; you can redistribute it and/or modify it under
374       the same terms as the Perl 5 programming language system itself.
375
376
377
378perl v5.34.1                      2022-04-25                   HTTP::Daemon(3)
Impressum