GSP
Quick Navigator

Search Site

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

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Net::FastCGI::Protocol(3) User Contributed Perl Documentation Net::FastCGI::Protocol(3)

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

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

Provides functions to build and parse FastCGI messages.

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.

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.

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.

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.

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.

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.

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.

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.

Builds "FCGI_NameValuePair"'s.

Usage

    $octets = build_params($params);

Arguments

$params
A hash reference containing name-value pairs.

Returns

$octets

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.

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).

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.

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.

Determine wheter 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 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 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.

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.

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.

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.

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.

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".

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

(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)

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

Christian Hansen "chansen@cpan.org"

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.

2010-04-21 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

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