Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  HTTP::PARSER::XS (3)

.ds Aq ’


HTTP::Parser::XS - a fast, primitive HTTP request parser



  use HTTP::Parser::XS qw(parse_http_request);

  # for HTTP servers
  my $ret = parse_http_request(
      "GET / HTTP/1.0\r\nHost: ...\r\n\r\n",
  if ($ret == -2) {
      # request is incomplete
  } elsif ($ret == -1) {
      # request is broken
  } else {
      # $ret includes the size of the request, %env now contains a PSGI
      # request, if it is a POST / PUT request, read request content by
      # yourself

  # for HTTP clients
  use HTTP::Parser::XS qw(parse_http_response HEADERS_AS_ARRAYREF);
  my %special_headers = (
    content-length => undef,
  my($ret, $minor_version, $status, $message, $headers)
    = parse_http_response($response, HEADERS_AS_ARRAYREF, \%special_headers);

  if($ret == -1) }
    # response is incomplete
  elsif($ret == -2) {
    # response is broken
  else {
    # $ret is the length of the headers, starting the content body

    # the other values are the response messages. For example:
    # $status  = 200
    # $message = "OK"
    # $headers = [ content-type => text/html, ... ]

    # and $special_headers{content-length} will be filled in


HTTP::Parser::XS is a fast, primitive HTTP request/response parser.

The request parser can be used either for writing a synchronous HTTP server or a event-driven server.

The response parser can be used for writing HTTP clients.

Note that even if this distribution name ends ::XS, <B>pure PerlB> implementation is supported, so you can use this module on compiler-less environments.


parse_http_request($request_string, \%env) Tries to parse given request string, and if successful, inserts variables into %env. For the name of the variables inserted, please refer to the PSGI specification. The return values are:
>=0 length of the request (request line and the request headers), in bytes
-1 given request is corrupt
-2 given request is incomplete

Note that the semantics of PATH_INFO is somewhat different from Apache. First, HTTP::Parser::XS does not validate the variable; it does not raise an error even if PATH_INFO does not start with /. Second, the variable is conformant to RFC 3875 (and PSGI / Plack) in the fact that // and .. appearing in PATH_INFO are preserved whereas Apache transcodes them.

parse_http_response($response_string, $header_format, \%special_headers) Tries to parse given response string. $header_format must be HEADERS_AS_ARRAYREF, HEADERS_AS_HASHREF, or HEADERS_NONE, which are exportable constants.

The optional %special_headers is for headers you specifically require. You can set any HTTP response header names, which must be lower-cased, and their default values, and then the values are filled in by parse_http_response(). For example, if you want the Cointent-Length field, set its name with default values like %h = (content-length => undef) and pass it as %special_headers. After parsing, $h{content-length} is set if the response has the Content-Length field, otherwise it’s not touched.

The return values are:
$ret The parsering status, which is the same as parse_http_response(). i.e. the length of the response headers in bytes, -1 for incomplete headers, or -2 for errors.

If the given response string is broken or imcomplete, parse_http_response() returns only this value.

$minor_version The minor version of the given response. i.e. 1 for HTTP/1.1, 0 for HTTP/1.0.
$status The HTTP status of the given response. e.g. 200 for success.
$message The HTTP status message. e.g. OK for success.
$headers The HTTP headers for the given response. It is an ARRAY reference if $header_format is HEADERS_AS_ARRAYREF, a HASH reference on HEADERS_AS_HASHREF, an undef on HEADERS_NONE.

The names of the headers are normalized to lower-cased.


Both parse_http_request() and parse_http_response() in XS implementation have some size limitations.

    The number of headers

The number of headers is limited to 128. If it exceeds, both parsing routines report parsing errors, i.e. return -1 for $ret.

    The size of header names

The size of header names is limited to 1024, but the parsers do not the same action.

parse_http_request() returns -1 if too-long header names exist.

parse_http_request() simply ignores too-long header names.


Copyright 2009- Kazuho Oku


o Kazuho Oku <>
o gfx <>
o mala <>
o tokuhirom <>


o nothingmuch <>
o charsbar <>


o <>
o HTTP::Parser
o HTTP::HeaderParser::XS
o Plack


This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 HTTP::PARSER::XS (3) 2014-12-15

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.