--- name: "Net::FastCGI::Protocol" section: "3pm" platform: "linux" package: "libnet-fastcgi-perl" version: "0.14-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Net::FastCGI::Protocol" --- # Net::FastCGI::Protocol(3pm) Provides functions to build and parse FastCGI messages. ## 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 \ - The Common Gateway Interface (CGI) Version 1.1 \ - 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.