.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::FastCGI::Protocol 3pm"
.TH Net::FastCGI::Protocol 3pm "2022-11-21" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::FastCGI::Protocol \- Provides functions to build and parse FastCGI messages.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    # FCGI_Header
\&    $octets = build_header($type, $request_id, $content_length, $padding_length);
\&    @values = parse_header($octets);
\&    $header = parse_header($octets);
\&    
\&    # FCGI_BeginRequestBody
\&    $octets = build_begin_request_body($role, $flags);
\&    @values = parse_begin_request_body($octets);
\&    
\&    # FCGI_EndRequestBody
\&    $octets = build_end_request_body($app_status, $protocol_status);
\&    @values = parse_end_request_body($octets);
\&    
\&    # FCGI_UnknownTypeBody
\&    $octets = build_unknown_type_body($type);
\&    @values = parse_unknown_type_body($octets);
\&    
\&    # FCGI_BeginRequestRecord
\&    $octets = build_begin_request_record($request_id, $role, $flags);
\&    
\&    # FCGI_EndRequestRecord
\&    $octets = build_end_request_record($request_id, $app_status, $protocol_status);
\&    
\&    # FCGI_UnknownTypeRecord
\&    $octets = build_unknown_type_record($type);
\&    
\&    # FCGI_NameValuePair\*(Aqs
\&    $octets = build_params($params);
\&    $params = parse_params($octets);
\&    $bool   = check_params($octets);
\&    
\&    # FCGI_Record
\&    $octets = build_record($type, $request_id);
\&    $octets = build_record($type, $request_id, $content);
\&    @values = parse_record($octets);
\&    $record = parse_record($octets);
\&    $record = parse_record_body($type, $request_id, $content);
\&    
\&    # FCGI_Record Debugging / Tracing
\&    $string = dump_record($octets);
\&    $string = dump_record_body($type, $request_id, $content);
\&    
\&    # FCGI_Record Stream
\&    $octets = build_stream($type, $request_id, $content);
\&    $octets = build_stream($type, $request_id, $content, $terminate);
\&    
\&    # Begin Request
\&    $octets = build_begin_request($request_id, $role, $flags, $params);
\&    $octets = build_begin_request($request_id, $role, $flags, $params, $stdin);
\&    $octets = build_begin_request($request_id, $role, $flags, $params, $stdin, $data);
\&    
\&    # End Request
\&    $octets = build_end_request($request_id, $app_status, $protocol_status);
\&    $octets = build_end_request($request_id, $app_status, $protocol_status, $stdout);
\&    $octets = build_end_request($request_id, $app_status, $protocol_status, $stdout, $stderr);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides functions to build and parse FastCGI messages.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
Please note that all functions in this package expects octets, not unicode strings.
It's the callers responsibility to ensure this. If any of theese functions is called
with unicode strings containing code points above 255, they will most likely produce
malformed messages.
.SS "build_begin_request"
.IX Subsection "build_begin_request"
Builds a Begin Request message.
.PP
\&\fIUsage\fR
.PP
.Vb 3
\&    $octets = build_begin_request($request_id, $role, $flags, $params);
\&    $octets = build_begin_request($request_id, $role, $flags, $params, $stdin);
\&    $octets = build_begin_request($request_id, $role, $flags, $params, $stdin, $data);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$request_id" 4
.el .IP "\f(CW$request_id\fR" 4
.IX Item "$request_id"
An unsigned 16\-bit integer. Identifier of the request.
.ie n .IP "$role" 4
.el .IP "\f(CW$role\fR" 4
.IX Item "$role"
An unsigned 16\-bit integer. This should be set to either \f(CW\*(C`FCGI_RESPONDER\*(C'\fR,
\&\f(CW\*(C`FCGI_AUTHORIZER\*(C'\fR or \f(CW\*(C`FCGI_FILTER\*(C'\fR.
.ie n .IP "$flags" 4
.el .IP "\f(CW$flags\fR" 4
.IX Item "$flags"
An unsigned 8\-bit integer. This should be set to either \f(CW0\fR or contain the 
mask \f(CW\*(C`FCGI_KEEP_CONN\*(C'\fR if a persistent connection is desired.
.ie n .IP "$params" 4
.el .IP "\f(CW$params\fR" 4
.IX Item "$params"
A hash reference containing name-value pairs. This is the \s-1CGI\s0 environ that the 
application expects.
.ie n .IP "$stdin (optional)" 4
.el .IP "\f(CW$stdin\fR (optional)" 4
.IX Item "$stdin (optional)"
A string of octets containing the \f(CW\*(C`FCGI_STDIN\*(C'\fR content. This should only be 
provided if \f(CW$role\fR is set to either \f(CW\*(C`FCGI_RESPONDER\*(C'\fR or \f(CW\*(C`FCGI_FILTER\*(C'\fR. The 
\&\f(CW\*(C`FCGI_STDIN\*(C'\fR stream is terminated if provided.
.ie n .IP "$data (optional)" 4
.el .IP "\f(CW$data\fR (optional)" 4
.IX Item "$data (optional)"
A string of octets containing the \f(CW\*(C`FCGI_DATA\*(C'\fR content. This should only be 
provided if \f(CW$role\fR is set to \f(CW\*(C`FCGI_FILTER\*(C'\fR. The \f(CW\*(C`FCGI_DATA\*(C'\fR stream is 
terminated if provided.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the message.
.SS "build_begin_request_body"
.IX Subsection "build_begin_request_body"
Builds a \f(CW\*(C`FCGI_BeginRequestBody\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $octets = build_begin_request_body($role, $flags);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$role" 4
.el .IP "\f(CW$role\fR" 4
.IX Item "$role"
An unsigned 16\-bit integer.
.ie n .IP "$flags" 4
.el .IP "\f(CW$flags\fR" 4
.IX Item "$flags"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the body. String is 8 octets in length.
.SS "build_begin_request_record"
.IX Subsection "build_begin_request_record"
Builds a \f(CW\*(C`FCGI_BeginRequestRecord\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $octets = build_begin_request_record($request_id, $role, $flags);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$request_id" 4
.el .IP "\f(CW$request_id\fR" 4
.IX Item "$request_id"
An unsigned 16\-bit integer.
.ie n .IP "$role" 4
.el .IP "\f(CW$role\fR" 4
.IX Item "$role"
An unsigned 16\-bit integer.
.ie n .IP "$flags" 4
.el .IP "\f(CW$flags\fR" 4
.IX Item "$flags"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the record. String is 16 octets in length.
.SS "build_end_request"
.IX Subsection "build_end_request"
Builds a End Request message
.PP
\&\fIUsage\fR
.PP
.Vb 3
\&    $octets = build_end_request($request_id, $app_status, $protocol_status);
\&    $octets = build_end_request($request_id, $app_status, $protocol_status, $stdout);
\&    $octets = build_end_request($request_id, $app_status, $protocol_status, $stdout, $stderr);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$request_id" 4
.el .IP "\f(CW$request_id\fR" 4
.IX Item "$request_id"
An unsigned 16\-bit integer. Identifier of the request.
.ie n .IP "$app_status" 4
.el .IP "\f(CW$app_status\fR" 4
.IX Item "$app_status"
An unsigned 32\-bit integer. Application status code of the request.
.ie n .IP "$protocol_status" 4
.el .IP "\f(CW$protocol_status\fR" 4
.IX Item "$protocol_status"
An unsigned 8\-bit integer. This should be set to either \f(CW\*(C`FCGI_REQUEST_COMPLETE\*(C'\fR,
\&\f(CW\*(C`FCGI_CANT_MPX_CONN\*(C'\fR, \f(CW\*(C`FCGI_OVERLOADED\*(C'\fR or \f(CW\*(C`FCGI_UNKNOWN_ROLE\*(C'\fR.
.ie n .IP "$stdout (optional)" 4
.el .IP "\f(CW$stdout\fR (optional)" 4
.IX Item "$stdout (optional)"
A string of octets containing the \f(CW\*(C`FCGI_STDOUT\*(C'\fR content. The \f(CW\*(C`FCGI_STDOUT\*(C'\fR
stream is terminated if provided.
.ie n .IP "$stderr (optional)" 4
.el .IP "\f(CW$stderr\fR (optional)" 4
.IX Item "$stderr (optional)"
A string of octets containing the \f(CW\*(C`FCGI_STDERR\*(C'\fR content. The \f(CW\*(C`FCGI_STDERR\*(C'\fR
stream is terminated if provided.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the message.
.PP
\&\fINote\fR
.PP
This function is equivalent to \f(CW\*(C`build_end_request_record()\*(C'\fR if called without
\&\f(CW$stdout\fR and \f(CW$stderr\fR.
.SS "build_end_request_body"
.IX Subsection "build_end_request_body"
Builds a \f(CW\*(C`FCGI_EndRequestBody\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $octets = build_end_request_body($app_status, $protocol_status);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$app_status" 4
.el .IP "\f(CW$app_status\fR" 4
.IX Item "$app_status"
An unsigned 32\-bit integer.
.ie n .IP "$protocol_status" 4
.el .IP "\f(CW$protocol_status\fR" 4
.IX Item "$protocol_status"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the body. String is 8 octets in length.
.SS "build_end_request_record"
.IX Subsection "build_end_request_record"
Builds a \f(CW\*(C`FCGI_EndRequestRecord\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $octets = build_end_request_record($request_id, $app_status, $protocol_status);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$request_id" 4
.el .IP "\f(CW$request_id\fR" 4
.IX Item "$request_id"
An unsigned 16\-bit integer.
.ie n .IP "$app_status" 4
.el .IP "\f(CW$app_status\fR" 4
.IX Item "$app_status"
An unsigned 32\-bit integer.
.ie n .IP "$protocol_status" 4
.el .IP "\f(CW$protocol_status\fR" 4
.IX Item "$protocol_status"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the record. String is 16 octets in length.
.SS "build_header"
.IX Subsection "build_header"
Builds a \f(CW\*(C`FCGI_Header\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $octets = build_header($type, $request_id, $content_length, $padding_length);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.ie n .IP "$request_id" 4
.el .IP "\f(CW$request_id\fR" 4
.IX Item "$request_id"
An unsigned 16\-bit integer.
.ie n .IP "$content_length" 4
.el .IP "\f(CW$content_length\fR" 4
.IX Item "$content_length"
An unsigned 16\-bit integer.
.ie n .IP "$padding_length" 4
.el .IP "\f(CW$padding_length\fR" 4
.IX Item "$padding_length"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the header. String is 8 octets in length.
.SS "build_params"
.IX Subsection "build_params"
Builds \f(CW\*(C`FCGI_NameValuePair\*(C'\fR's.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $octets = build_params($params);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$params" 4
.el .IP "\f(CW$params\fR" 4
.IX Item "$params"
A hash reference containing name-value pairs.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
.SS "build_record"
.IX Subsection "build_record"
Builds a \f(CW\*(C`FCGI_Record\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 2
\&    $octets = build_record($type, $request_id);
\&    $octets = build_record($type, $request_id, $content);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.ie n .IP "$request_id" 4
.el .IP "\f(CW$request_id\fR" 4
.IX Item "$request_id"
An unsigned 16\-bit integer.
.ie n .IP "$content (optional)" 4
.el .IP "\f(CW$content\fR (optional)" 4
.IX Item "$content (optional)"
A string of octets containing the content, cannot exceed 65535 octets in length.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the record.
.PP
\&\fINote\fR
.PP
Follows the recommendation in specification and pads the record by 
8\-(content_length mod 8) zero-octets.
.SS "build_stream"
.IX Subsection "build_stream"
Builds a series of stream records.
.PP
\&\fIUsage\fR
.PP
.Vb 2
\&    $octets = build_stream($type, $request_id, $content);
\&    $octets = build_stream($type, $request_id, $content, $terminate);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.ie n .IP "$request_id" 4
.el .IP "\f(CW$request_id\fR" 4
.IX Item "$request_id"
An unsigned 16\-bit integer.
.ie n .IP "$content" 4
.el .IP "\f(CW$content\fR" 4
.IX Item "$content"
A string of octets containing the stream content.
.ie n .IP "$terminate (optional)" 4
.el .IP "\f(CW$terminate\fR (optional)" 4
.IX Item "$terminate (optional)"
A boolean indicating whether or not the stream should be terminated.
Defaults to false.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the stream.
.PP
\&\fINote\fR
.PP
Stream is not terminated if \f(CW$content\fR is empty unless \f(CW$terminate\fR is set.
.PP
\&\f(CW$content\fR is split in segment sizes of 32760 octets (32768 \- \s-1FCGI_HEADER_LEN\s0).
.SS "build_unknown_type_body"
.IX Subsection "build_unknown_type_body"
Builds a \f(CW\*(C`FCGI_UnknownTypeBody\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $octets = build_unknown_type_body($type);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the body. String is 8 octets in length.
.SS "build_unknown_type_record"
.IX Subsection "build_unknown_type_record"
Builds a \f(CW\*(C`FCGI_UnknownTypRecord\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $octets = build_unknown_type_record($type);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the record. String is 16 octets in length.
.SS "check_params"
.IX Subsection "check_params"
Determine whether or not params is well-formed.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $boolean = check_params($octets);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing \f(CW\*(C`FCGI_NameValuePair\*(C'\fR's.
.PP
\&\fIReturns\fR
.ie n .IP "$boolean" 4
.el .IP "\f(CW$boolean\fR" 4
.IX Item "$boolean"
A boolean indicating whether or not \f(CW$octets\fR consist of well-formed \f(CW\*(C`FCGI_NameValuePair\*(C'\fR's.
.SS "dump_record"
.IX Subsection "dump_record"
Dump a \f(CW\*(C`FCGI_Record\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $string = dump_record($octets);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing at least one record.
.PP
\&\fIReturns\fR
.ie n .IP "$string" 4
.el .IP "\f(CW$string\fR" 4
.IX Item "$string"
A short (less than 100 characters) string representation of the record in printable US-ASCII.
.SS "dump_record_body"
.IX Subsection "dump_record_body"
Dump a \f(CW\*(C`FCGI_Record\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 2
\&    $string = dump_record_body($type, $request_id);
\&    $string = dump_record_body($type, $request_id, $content);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.ie n .IP "$request_id" 4
.el .IP "\f(CW$request_id\fR" 4
.IX Item "$request_id"
An unsigned 16\-bit integer.
.ie n .IP "$content (optional)" 4
.el .IP "\f(CW$content\fR (optional)" 4
.IX Item "$content (optional)"
A string of octets containing the content.
.PP
\&\fIReturns\fR
.ie n .IP "$string" 4
.el .IP "\f(CW$string\fR" 4
.IX Item "$string"
A short (less than 100 characters) string representation of the record in printable US-ASCII.
.SS "parse_begin_request_body"
.IX Subsection "parse_begin_request_body"
Parses a \f(CW\*(C`FCGI_BeginRequestBody\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    ($role, $flags) = parse_begin_request_body($octets);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the body, must be greater than or equal to 8 octets in length.
.PP
\&\fIReturns\fR
.ie n .IP "$role" 4
.el .IP "\f(CW$role\fR" 4
.IX Item "$role"
An unsigned 16\-bit integer.
.ie n .IP "$flags" 4
.el .IP "\f(CW$flags\fR" 4
.IX Item "$flags"
An unsigned 8\-bit integer.
.SS "parse_end_request_body"
.IX Subsection "parse_end_request_body"
Parses a \f(CW\*(C`FCGI_EndRequestBody\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    ($app_status, $protocol_status) = parse_end_request_body($octets);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the body, must be greater than or equal to 8 octets in length.
.PP
\&\fIReturns\fR
.ie n .IP "$app_status" 4
.el .IP "\f(CW$app_status\fR" 4
.IX Item "$app_status"
An unsigned 32\-bit integer.
.ie n .IP "$flags" 4
.el .IP "\f(CW$flags\fR" 4
.IX Item "$flags"
An unsigned 8\-bit integer.
.SS "parse_header"
.IX Subsection "parse_header"
Parses a \f(CW\*(C`FCGI_Header\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 2
\&    ($type, $request_id, $content_length, $padding_length)
\&      = parse_header($octets);
\&    
\&    $header = parse_header($octets);
\&    say $header\->{type};
\&    say $header\->{request_id};
\&    say $header\->{content_length};
\&    say $header\->{padding_length};
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing the header, must be greater than or equal to 8 octets in length.
.PP
\&\fIReturns\fR
.PP
In list context:
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.ie n .IP "$request_id" 4
.el .IP "\f(CW$request_id\fR" 4
.IX Item "$request_id"
An unsigned 16\-bit integer.
.ie n .IP "$content_length" 4
.el .IP "\f(CW$content_length\fR" 4
.IX Item "$content_length"
An unsigned 16\-bit integer.
.ie n .IP "$padding_length" 4
.el .IP "\f(CW$padding_length\fR" 4
.IX Item "$padding_length"
An unsigned 8\-bit integer.
.PP
In scalar context a hash reference containing above variable names as keys.
.SS "parse_params"
.IX Subsection "parse_params"
Parses \f(CW\*(C`FCGI_NameValuePair\*(C'\fR's.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $params = parse_params($octets);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing \f(CW\*(C`FCGI_NameValuePair\*(C'\fR's.
.PP
\&\fIReturns\fR
.ie n .IP "$params" 4
.el .IP "\f(CW$params\fR" 4
.IX Item "$params"
A hash reference containing name-value pairs.
.SS "parse_record"
.IX Subsection "parse_record"
Parses a \f(CW\*(C`FCGI_Record\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 2
\&    ($type, $request_id, $content)
\&      = parse_record($octets);
\&
\&    $record = parse_record($octets);
\&    say $record\->{type};
\&    say $record\->{request_id};
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing at least one record.
.PP
\&\fIReturns\fR
.PP
In list context:
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.ie n .IP "$request_id" 4
.el .IP "\f(CW$request_id\fR" 4
.IX Item "$request_id"
An unsigned 16\-bit integer.
.ie n .IP "$content" 4
.el .IP "\f(CW$content\fR" 4
.IX Item "$content"
A string of octets containing the record content.
.PP
In scalar context a hash reference containing the \f(CW\*(C`FCGI_Record\*(C'\fR components. 
See \*(L"parse_record_body\*(R".
.SS "parse_record_body"
.IX Subsection "parse_record_body"
Parses a \f(CW\*(C`FCGI_Record\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 3
\&    $record = parse_record_body($type, $request_id, $content);
\&    say $record\->{type};
\&    say $record\->{request_id};
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.ie n .IP "$request_id" 4
.el .IP "\f(CW$request_id\fR" 4
.IX Item "$request_id"
An unsigned 16\-bit integer.
.ie n .IP "$content" 4
.el .IP "\f(CW$content\fR" 4
.IX Item "$content"
A string of octets containing the record content.
.PP
\&\fIReturns\fR
.PP
A hash reference which represents the \f(CW\*(C`FCGI_Record\*(C'\fR. The content depends on the
type of record. All record types have the keys: \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`request_id\*(C'\fR.
.ie n .IP """FCGI_BEGIN_REQUEST""" 4
.el .IP "\f(CWFCGI_BEGIN_REQUEST\fR" 4
.IX Item "FCGI_BEGIN_REQUEST"
.RS 4
.PD 0
.ie n .IP """role""" 8
.el .IP "\f(CWrole\fR" 8
.IX Item "role"
.PD
An unsigned 16\-bit integer.
.ie n .IP """flags""" 8
.el .IP "\f(CWflags\fR" 8
.IX Item "flags"
An unsigned 8\-bit integer.
.RE
.RS 4
.RE
.ie n .IP """FCGI_END_REQUEST""" 4
.el .IP "\f(CWFCGI_END_REQUEST\fR" 4
.IX Item "FCGI_END_REQUEST"
.RS 4
.PD 0
.ie n .IP """app_status""" 8
.el .IP "\f(CWapp_status\fR" 8
.IX Item "app_status"
.PD
An unsigned 32\-bit integer.
.ie n .IP """protocol_status""" 8
.el .IP "\f(CWprotocol_status\fR" 8
.IX Item "protocol_status"
An unsigned 8\-bit integer.
.RE
.RS 4
.RE
.ie n .IP """FCGI_PARAMS""" 4
.el .IP "\f(CWFCGI_PARAMS\fR" 4
.IX Item "FCGI_PARAMS"
.PD 0
.ie n .IP """FCGI_STDIN""" 4
.el .IP "\f(CWFCGI_STDIN\fR" 4
.IX Item "FCGI_STDIN"
.ie n .IP """FCGI_DATA""" 4
.el .IP "\f(CWFCGI_DATA\fR" 4
.IX Item "FCGI_DATA"
.ie n .IP """FCGI_STDOUT""" 4
.el .IP "\f(CWFCGI_STDOUT\fR" 4
.IX Item "FCGI_STDOUT"
.ie n .IP """FCGI_STDERR""" 4
.el .IP "\f(CWFCGI_STDERR\fR" 4
.IX Item "FCGI_STDERR"
.RS 4
.ie n .IP """content""" 8
.el .IP "\f(CWcontent\fR" 8
.IX Item "content"
.PD
A string of octets containing the content of the stream.
.RE
.RS 4
.RE
.ie n .IP """FCGI_GET_VALUES""" 4
.el .IP "\f(CWFCGI_GET_VALUES\fR" 4
.IX Item "FCGI_GET_VALUES"
.PD 0
.ie n .IP """FCGI_GET_VALUES_RESULT""" 4
.el .IP "\f(CWFCGI_GET_VALUES_RESULT\fR" 4
.IX Item "FCGI_GET_VALUES_RESULT"
.RS 4
.ie n .IP """values""" 8
.el .IP "\f(CWvalues\fR" 8
.IX Item "values"
.PD
A hash reference containing name-value pairs.
.RE
.RS 4
.RE
.ie n .IP """FCGI_UNKNOWN_TYPE""" 4
.el .IP "\f(CWFCGI_UNKNOWN_TYPE\fR" 4
.IX Item "FCGI_UNKNOWN_TYPE"
.RS 4
.PD 0
.ie n .IP """unknown_type""" 8
.el .IP "\f(CWunknown_type\fR" 8
.IX Item "unknown_type"
.PD
An unsigned 8\-bit integer.
.RE
.RS 4
.RE
.SS "parse_unknown_type_body"
.IX Subsection "parse_unknown_type_body"
Parses a \f(CW\*(C`FCGI_UnknownTypeBody\*(C'\fR.
.PP
\&\fIUsage\fR
.PP
.Vb 1
\&    $type = parse_unknown_type_body($octets);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
\&\f(CW$octets\fR must be greater than or equal to 8 octets in length.
.PP
\&\fIReturns\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.SS "get_record_length"
.IX Subsection "get_record_length"
\&\fIUsage\fR
.PP
.Vb 1
\&    $length = get_record_length($octets);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$octets" 4
.el .IP "\f(CW$octets\fR" 4
.IX Item "$octets"
A string of octets containing at least one \f(CW\*(C`FCGI_Header\*(C'\fR.
.PP
\&\fIReturns\fR
.ie n .IP "$length" 4
.el .IP "\f(CW$length\fR" 4
.IX Item "$length"
An unsigned integer containing the length of record in octets. If \f(CW$octets\fR 
contains insufficient octets \f(CW\*(C`(< FCGI_HEADER_LEN)\*(C'\fR \f(CW0\fR is returned.
.SS "get_type_name"
.IX Subsection "get_type_name"
\&\fIUsage\fR
.PP
.Vb 3
\&    $name = get_type_name($type);
\&    $name = get_type_name(FCGI_BEGIN_REQUEST);  # \*(AqFCGI_BEGIN_REQUEST\*(Aq
\&    $name = get_type_name(255);                 # \*(Aq0xFF\*(Aq
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$name" 4
.el .IP "\f(CW$name\fR" 4
.IX Item "$name"
A string containing the name of the type. If \f(CW$type\fR is not a known v1.0 type,
a hexadecimal value is returned.
.PP
\&\fINote\fR
.PP
See also \*(L":name\*(R" in Net::FastCGI::Constant.
.SS "get_role_name"
.IX Subsection "get_role_name"
\&\fIUsage\fR
.PP
.Vb 3
\&    $name = get_role_name($type);
\&    $name = get_role_name(FCGI_RESPONDER);  # \*(AqFCGI_RESPONDER\*(Aq
\&    $name = get_role_name(65535);           # \*(Aq0xFFFF\*(Aq
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$role" 4
.el .IP "\f(CW$role\fR" 4
.IX Item "$role"
An unsigned 16\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$name" 4
.el .IP "\f(CW$name\fR" 4
.IX Item "$name"
A string containing the name of the role. If \f(CW$role\fR is not a known v1.0 role, 
a hexadecimal value is returned.
.PP
\&\fINote\fR
.PP
See also \*(L":name\*(R" in Net::FastCGI::Constant.
.SS "get_protocol_status_name"
.IX Subsection "get_protocol_status_name"
\&\fIUsage\fR
.PP
.Vb 3
\&    $name = get_protocol_status_name($protocol_status);
\&    $name = get_protocol_status_name(FCGI_REQUEST_COMPLETE);    # \*(AqFCGI_REQUEST_COMPLETE\*(Aq
\&    $name = get_protocol_status_name(255);                      # \*(Aq0xFF\*(Aq
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$protocol_status" 4
.el .IP "\f(CW$protocol_status\fR" 4
.IX Item "$protocol_status"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$name" 4
.el .IP "\f(CW$name\fR" 4
.IX Item "$name"
A string containing the name of the protocol status. If \f(CW$protocol_status\fR is 
not a known v1.0 protocol status code, a hexadecimal value is returned.
.PP
\&\fINote\fR
.PP
See also \*(L":name\*(R" in Net::FastCGI::Constant.
.SS "is_known_type"
.IX Subsection "is_known_type"
\&\fIUsage\fR
.PP
.Vb 1
\&    $boolean = is_known_type($type);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$boolean" 4
.el .IP "\f(CW$boolean\fR" 4
.IX Item "$boolean"
A boolean indicating whether or not \f(CW$type\fR is a known FastCGI v1.0 type.
.SS "is_management_type"
.IX Subsection "is_management_type"
\&\fIUsage\fR
.PP
.Vb 1
\&    $boolean = is_management_type($type);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$boolean" 4
.el .IP "\f(CW$boolean\fR" 4
.IX Item "$boolean"
A boolean indicating whether or not \f(CW$type\fR is a management type.
.SS "is_discrete_type"
.IX Subsection "is_discrete_type"
\&\fIUsage\fR
.PP
.Vb 1
\&    $boolean = is_discrete_type($type);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$boolean" 4
.el .IP "\f(CW$boolean\fR" 4
.IX Item "$boolean"
A boolean indicating whether or not \f(CW$type\fR is a discrete type.
.SS "is_stream_type"
.IX Subsection "is_stream_type"
\&\fIUsage\fR
.PP
.Vb 1
\&    $boolean = is_stream_type($type);
.Ve
.PP
\&\fIArguments\fR
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
An unsigned 8\-bit integer.
.PP
\&\fIReturns\fR
.ie n .IP "$boolean" 4
.el .IP "\f(CW$boolean\fR" 4
.IX Item "$boolean"
A boolean indicating whether or not \f(CW$type\fR is a stream type.
.SH "EXPORTS"
.IX Header "EXPORTS"
None by default. All functions can be exported using the \f(CW\*(C`:all\*(C'\fR tag or individually.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP "\fB(F)\fR Usage: %s" 4
.el .IP "\fB(F)\fR Usage: \f(CW%s\fR" 4
.IX Item "(F) Usage: %s"
Subroutine called with wrong number of arguments.
.ie n .IP "\fB(F)\fR Invalid Argument: %s" 4
.el .IP "\fB(F)\fR Invalid Argument: \f(CW%s\fR" 4
.IX Item "(F) Invalid Argument: %s"
.PD 0
.ie n .IP "\fB(F)\fR FastCGI: Insufficient number of octets to parse %s" 4
.el .IP "\fB(F)\fR FastCGI: Insufficient number of octets to parse \f(CW%s\fR" 4
.IX Item "(F) FastCGI: Insufficient number of octets to parse %s"
.ie n .IP "\fB(F)\fR FastCGI: Malformed record %s" 4
.el .IP "\fB(F)\fR FastCGI: Malformed record \f(CW%s\fR" 4
.IX Item "(F) FastCGI: Malformed record %s"
.IP "\fB(F)\fR FastCGI: Protocol version mismatch (0x%.2X)" 4
.IX Item "(F) FastCGI: Protocol version mismatch (0x%.2X)"
.PD
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "FastCGI Specification Version 1.0" 4
.IX Item "FastCGI Specification Version 1.0"
<http://www.fastcgi.com/devkit/doc/fcgi\-spec.html>
.IP "The Common Gateway Interface (\s-1CGI\s0) Version 1.1" 4
.IX Item "The Common Gateway Interface (CGI) Version 1.1"
<http://tools.ietf.org/html/rfc3875>
.IP "Net::FastCGI::Constant" 4
.IX Item "Net::FastCGI::Constant"
.SH "AUTHOR"
.IX Header "AUTHOR"
Christian Hansen \f(CW\*(C`chansen@cpan.org\*(C'\fR
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2010 by Christian Hansen.
.PP
This library is free software; you can redistribute it and/or modify 
it under the same terms as Perl itself.