Provided by: libnet-fastcgi-perl_0.14-2_all bug

NAME

       Net::FastCGI::Protocol - Provides functions to build and parse FastCGI messages.

SYNOPSIS

           # 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's
           $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);

DESCRIPTION

       Provides functions to build and parse FastCGI messages.

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.

   build_begin_request
       Builds a Begin Request message.

       Usage

           $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);

       Arguments

       $request_id
           An unsigned 16-bit integer. Identifier of the request.

       $role
           An unsigned 16-bit integer. This should be set to either "FCGI_RESPONDER",
           "FCGI_AUTHORIZER" or "FCGI_FILTER".

       $flags
           An unsigned 8-bit integer. This should be set to either 0 or contain the mask
           "FCGI_KEEP_CONN" if a persistent connection is desired.

       $params
           A hash reference containing name-value pairs. This is the CGI environ that the
           application expects.

       $stdin (optional)
           A string of octets containing the "FCGI_STDIN" content. This should only be provided
           if $role is set to either "FCGI_RESPONDER" or "FCGI_FILTER". The "FCGI_STDIN" stream
           is terminated if provided.

       $data (optional)
           A string of octets containing the "FCGI_DATA" content. This should only be provided if
           $role is set to "FCGI_FILTER". The "FCGI_DATA" stream is terminated if provided.

       Returns

       $octets
           A string of octets containing the message.

   build_begin_request_body
       Builds a "FCGI_BeginRequestBody".

       Usage

           $octets = build_begin_request_body($role, $flags);

       Arguments

       $role
           An unsigned 16-bit integer.

       $flags
           An unsigned 8-bit integer.

       Returns

       $octets
           A string of octets containing the body. String is 8 octets in length.

   build_begin_request_record
       Builds a "FCGI_BeginRequestRecord".

       Usage

           $octets = build_begin_request_record($request_id, $role, $flags);

       Arguments

       $request_id
           An unsigned 16-bit integer.

       $role
           An unsigned 16-bit integer.

       $flags
           An unsigned 8-bit integer.

       Returns

       $octets
           A string of octets containing the record. String is 16 octets in length.

   build_end_request
       Builds a End Request message

       Usage

           $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);

       Arguments

       $request_id
           An unsigned 16-bit integer. Identifier of the request.

       $app_status
           An unsigned 32-bit integer. Application status code of the request.

       $protocol_status
           An unsigned 8-bit integer. This should be set to either "FCGI_REQUEST_COMPLETE",
           "FCGI_CANT_MPX_CONN", "FCGI_OVERLOADED" or "FCGI_UNKNOWN_ROLE".

       $stdout (optional)
           A string of octets containing the "FCGI_STDOUT" content. The "FCGI_STDOUT" stream is
           terminated if provided.

       $stderr (optional)
           A string of octets containing the "FCGI_STDERR" content. The "FCGI_STDERR" stream is
           terminated if provided.

       Returns

       $octets
           A string of octets containing the message.

       Note

       This function is equivalent to "build_end_request_record()" if called without $stdout and
       $stderr.

   build_end_request_body
       Builds a "FCGI_EndRequestBody".

       Usage

           $octets = build_end_request_body($app_status, $protocol_status);

       Arguments

       $app_status
           An unsigned 32-bit integer.

       $protocol_status
           An unsigned 8-bit integer.

       Returns

       $octets
           A string of octets containing the body. String is 8 octets in length.

   build_end_request_record
       Builds a "FCGI_EndRequestRecord".

       Usage

           $octets = build_end_request_record($request_id, $app_status, $protocol_status);

       Arguments

       $request_id
           An unsigned 16-bit integer.

       $app_status
           An unsigned 32-bit integer.

       $protocol_status
           An unsigned 8-bit integer.

       Returns

       $octets
           A string of octets containing the record. String is 16 octets in length.

   build_header
       Builds a "FCGI_Header".

       Usage

           $octets = build_header($type, $request_id, $content_length, $padding_length);

       Arguments

       $type
           An unsigned 8-bit integer.

       $request_id
           An unsigned 16-bit integer.

       $content_length
           An unsigned 16-bit integer.

       $padding_length
           An unsigned 8-bit integer.

       Returns

       $octets
           A string of octets containing the header. String is 8 octets in length.

   build_params
       Builds "FCGI_NameValuePair"'s.

       Usage

           $octets = build_params($params);

       Arguments

       $params
           A hash reference containing name-value pairs.

       Returns

       $octets

   build_record
       Builds a "FCGI_Record".

       Usage

           $octets = build_record($type, $request_id);
           $octets = build_record($type, $request_id, $content);

       Arguments

       $type
           An unsigned 8-bit integer.

       $request_id
           An unsigned 16-bit integer.

       $content (optional)
           A string of octets containing the content, cannot exceed 65535 octets in length.

       Returns

       $octets
           A string of octets containing the record.

       Note

       Follows the recommendation in specification and pads the record by 8-(content_length mod
       8) zero-octets.

   build_stream
       Builds a series of stream records.

       Usage

           $octets = build_stream($type, $request_id, $content);
           $octets = build_stream($type, $request_id, $content, $terminate);

       Arguments

       $type
           An unsigned 8-bit integer.

       $request_id
           An unsigned 16-bit integer.

       $content
           A string of octets containing the stream content.

       $terminate (optional)
           A boolean indicating whether or not the stream should be terminated.  Defaults to
           false.

       Returns

       $octets
           A string of octets containing the stream.

       Note

       Stream is not terminated if $content is empty unless $terminate is set.

       $content is split in segment sizes of 32760 octets (32768 - FCGI_HEADER_LEN).

   build_unknown_type_body
       Builds a "FCGI_UnknownTypeBody".

       Usage

           $octets = build_unknown_type_body($type);

       Arguments

       $type
           An unsigned 8-bit integer.

       Returns

       $octets
           A string of octets containing the body. String is 8 octets in length.

   build_unknown_type_record
       Builds a "FCGI_UnknownTypRecord".

       Usage

           $octets = build_unknown_type_record($type);

       Arguments

       $type
           An unsigned 8-bit integer.

       Returns

       $octets
           A string of octets containing the record. String is 16 octets in length.

   check_params
       Determine whether or not params is well-formed.

       Usage

           $boolean = check_params($octets);

       Arguments

       $octets
           A string of octets containing "FCGI_NameValuePair"'s.

       Returns

       $boolean
           A boolean indicating whether or not $octets consist of well-formed
           "FCGI_NameValuePair"'s.

   dump_record
       Dump a "FCGI_Record".

       Usage

           $string = dump_record($octets);

       Arguments

       $octets
           A string of octets containing at least one record.

       Returns

       $string
           A short (less than 100 characters) string representation of the record in printable
           US-ASCII.

   dump_record_body
       Dump a "FCGI_Record".

       Usage

           $string = dump_record_body($type, $request_id);
           $string = dump_record_body($type, $request_id, $content);

       Arguments

       $type
           An unsigned 8-bit integer.

       $request_id
           An unsigned 16-bit integer.

       $content (optional)
           A string of octets containing the content.

       Returns

       $string
           A short (less than 100 characters) string representation of the record in printable
           US-ASCII.

   parse_begin_request_body
       Parses a "FCGI_BeginRequestBody".

       Usage

           ($role, $flags) = parse_begin_request_body($octets);

       Arguments

       $octets
           A string of octets containing the body, must be greater than or equal to 8 octets in
           length.

       Returns

       $role
           An unsigned 16-bit integer.

       $flags
           An unsigned 8-bit integer.

   parse_end_request_body
       Parses a "FCGI_EndRequestBody".

       Usage

           ($app_status, $protocol_status) = parse_end_request_body($octets);

       Arguments

       $octets
           A string of octets containing the body, must be greater than or equal to 8 octets in
           length.

       Returns

       $app_status
           An unsigned 32-bit integer.

       $flags
           An unsigned 8-bit integer.

   parse_header
       Parses a "FCGI_Header".

       Usage

           ($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};

       Arguments

       $octets
           A string of octets containing the header, must be greater than or equal to 8 octets in
           length.

       Returns

       In list context:

       $type
           An unsigned 8-bit integer.

       $request_id
           An unsigned 16-bit integer.

       $content_length
           An unsigned 16-bit integer.

       $padding_length
           An unsigned 8-bit integer.

       In scalar context a hash reference containing above variable names as keys.

   parse_params
       Parses "FCGI_NameValuePair"'s.

       Usage

           $params = parse_params($octets);

       Arguments

       $octets
           A string of octets containing "FCGI_NameValuePair"'s.

       Returns

       $params
           A hash reference containing name-value pairs.

   parse_record
       Parses a "FCGI_Record".

       Usage

           ($type, $request_id, $content)
             = parse_record($octets);

           $record = parse_record($octets);
           say $record->{type};
           say $record->{request_id};

       Arguments

       $octets
           A string of octets containing at least one record.

       Returns

       In list context:

       $type
           An unsigned 8-bit integer.

       $request_id
           An unsigned 16-bit integer.

       $content
           A string of octets containing the record content.

       In scalar context a hash reference containing the "FCGI_Record" components.  See
       "parse_record_body".

   parse_record_body
       Parses a "FCGI_Record".

       Usage

           $record = parse_record_body($type, $request_id, $content);
           say $record->{type};
           say $record->{request_id};

       Arguments

       $type
           An unsigned 8-bit integer.

       $request_id
           An unsigned 16-bit integer.

       $content
           A string of octets containing the record content.

       Returns

       A hash reference which represents the "FCGI_Record". The content depends on the type of
       record. All record types have the keys: "type" and "request_id".

       "FCGI_BEGIN_REQUEST"
           "role"  An unsigned 16-bit integer.

           "flags" An unsigned 8-bit integer.

       "FCGI_END_REQUEST"
           "app_status"
                   An unsigned 32-bit integer.

           "protocol_status"
                   An unsigned 8-bit integer.

       "FCGI_PARAMS"
       "FCGI_STDIN"
       "FCGI_DATA"
       "FCGI_STDOUT"
       "FCGI_STDERR"
           "content"
                   A string of octets containing the content of the stream.

       "FCGI_GET_VALUES"
       "FCGI_GET_VALUES_RESULT"
           "values"
                   A hash reference containing name-value pairs.

       "FCGI_UNKNOWN_TYPE"
           "unknown_type"
                   An unsigned 8-bit integer.

   parse_unknown_type_body
       Parses a "FCGI_UnknownTypeBody".

       Usage

           $type = parse_unknown_type_body($octets);

       Arguments

       $octets
           $octets must be greater than or equal to 8 octets in length.

       Returns

       $type
           An unsigned 8-bit integer.

   get_record_length
       Usage

           $length = get_record_length($octets);

       Arguments

       $octets
           A string of octets containing at least one "FCGI_Header".

       Returns

       $length
           An unsigned integer containing the length of record in octets. If $octets contains
           insufficient octets "(< FCGI_HEADER_LEN)" 0 is returned.

   get_type_name
       Usage

           $name = get_type_name($type);
           $name = get_type_name(FCGI_BEGIN_REQUEST);  # 'FCGI_BEGIN_REQUEST'
           $name = get_type_name(255);                 # '0xFF'

       Arguments

       $type
           An unsigned 8-bit integer.

       Returns

       $name
           A string containing the name of the type. If $type is not a known v1.0 type, a
           hexadecimal value is returned.

       Note

       See also ":name" in Net::FastCGI::Constant.

   get_role_name
       Usage

           $name = get_role_name($type);
           $name = get_role_name(FCGI_RESPONDER);  # 'FCGI_RESPONDER'
           $name = get_role_name(65535);           # '0xFFFF'

       Arguments

       $role
           An unsigned 16-bit integer.

       Returns

       $name
           A string containing the name of the role. If $role is not a known v1.0 role, a
           hexadecimal value is returned.

       Note

       See also ":name" in Net::FastCGI::Constant.

   get_protocol_status_name
       Usage

           $name = get_protocol_status_name($protocol_status);
           $name = get_protocol_status_name(FCGI_REQUEST_COMPLETE);    # 'FCGI_REQUEST_COMPLETE'
           $name = get_protocol_status_name(255);                      # '0xFF'

       Arguments

       $protocol_status
           An unsigned 8-bit integer.

       Returns

       $name
           A string containing the name of the protocol status. If $protocol_status is not a
           known v1.0 protocol status code, a hexadecimal value is returned.

       Note

       See also ":name" in Net::FastCGI::Constant.

   is_known_type
       Usage

           $boolean = is_known_type($type);

       Arguments

       $type
           An unsigned 8-bit integer.

       Returns

       $boolean
           A boolean indicating whether or not $type is a known FastCGI v1.0 type.

   is_management_type
       Usage

           $boolean = is_management_type($type);

       Arguments

       $type
           An unsigned 8-bit integer.

       Returns

       $boolean
           A boolean indicating whether or not $type is a management type.

   is_discrete_type
       Usage

           $boolean = is_discrete_type($type);

       Arguments

       $type
           An unsigned 8-bit integer.

       Returns

       $boolean
           A boolean indicating whether or not $type is a discrete type.

   is_stream_type
       Usage

           $boolean = is_stream_type($type);

       Arguments

       $type
           An unsigned 8-bit integer.

       Returns

       $boolean
           A boolean indicating whether or not $type is a stream type.

EXPORTS

       None by default. All functions can be exported using the ":all" tag or individually.

DIAGNOSTICS

       (F) Usage: %s
           Subroutine called with wrong number of arguments.

       (F) Invalid Argument: %s
       (F) FastCGI: Insufficient number of octets to parse %s
       (F) FastCGI: Malformed record %s
       (F) FastCGI: Protocol version mismatch (0x%.2X)

SEE ALSO

       FastCGI Specification Version 1.0
           <http://www.fastcgi.com/devkit/doc/fcgi-spec.html>

       The Common Gateway Interface (CGI) Version 1.1
           <http://tools.ietf.org/html/rfc3875>

       Net::FastCGI::Constant

AUTHOR

       Christian Hansen "chansen@cpan.org"

COPYRIGHT

       Copyright 2008-2010 by Christian Hansen.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.