Net::F...otocol(3pm)

📦

version 0.14 · 2 versions

0.14 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
0.14 · ubuntu jammy

, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ NAME ✨

Net::FastCGI::Protocol — bestie, this is the Net::FastCGI::Protocol(3pm) page (it lives in the User Contributed Perl Documentation corner of the manual), and it's the whole toolkit for building and parsing FastCGI messages. 💅

🎀 SYNOPSIS 🎀

okay so here's the vibe, all the moves in one place:

# 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 🌸

It provides functions to build and parse FastCGI messages. That's the whole gig and she ate. 💖

👑 FUNCTIONS 👑

⚠️ real talk first: every single function in this package expects octets, NOT unicode strings. It's 100% the caller's job to make sure of that. If any of these functions gets called with unicode strings that have code points above 255, they will most likely produce malformed messages. Not a vibe. 😭

🦋 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. The request's identifier. 🏷️
$role — an unsigned 16-bit integer. Set it to either FCGI_RESPONDER, FCGI_AUTHORIZER or FCGI_FILTER.
$flags — an unsigned 8-bit integer. Should be set to either 0, or contain the mask FCGI_KEEP_CONN if a persistent connection is what you want.
$params — a hash reference holding name-value pairs. This is the CGI environ the application expects.
$stdin (optional) — a string of octets containing the FCGI_STDIN content. Only provide this if $role is set to either FCGI_RESPONDER or FCGI_FILTER. The FCGI_STDIN stream gets terminated if it's provided.
$data (optional) — a string of octets containing the FCGI_DATA content. Only provide this if $role is set to FCGI_FILTER. The FCGI_DATA stream gets terminated if it's 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. The 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. The 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. The request's identifier. 🏷️
$app_status — an unsigned 32-bit integer. The application status code of the request.
$protocol_status — an unsigned 8-bit integer. Set it 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 gets terminated if it's provided.
$stderr (optional) — a string of octets containing the FCGI_STDERR content. The FCGI_STDERR stream gets terminated if it's provided.

Returns

$octets — a string of octets containing the message.

Note

This function is equivalent to build_end_request_record() if you call it without $stdout and $stderr. iykyk ✨

🌈 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. The 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. The 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. The 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. It cannot exceed 65535 octets in length.

Returns

$octets — a string of octets containing the record.

Note

It follows the recommendation in the specification and pads the record by 8-(content_length mod 8) zero-octets. periodt. 💅

🧚 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 saying whether or not the stream should be terminated. Defaults to false.

Returns

$octets — a string of octets containing the stream.

Note

The stream is not terminated if $content is empty, unless $terminate is set.

$content gets split into 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. The string is 8 octets in length.

💜 build_unknown_type_record

Builds a FCGI_UnknownTypRecord. (yes that spelling is what the page says, don't come for me 🙈)

Usage

$octets = build_unknown_type_record($type);

Arguments

$type — an unsigned 8-bit integer.

Returns

$octets — a string of octets containing the record. The string is 16 octets in length.

👑 check_params

Figure out whether or not the params are well-formed.

Usage

$boolean = check_params($octets);

Arguments

$octets — a string of octets containing FCGI_NameValuePair's.

Returns

$boolean — a boolean saying whether or not $octets consists 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

so the $octets for this one is a string of octets holding the body, and bestie it must be greater than or equal to 8 octets in length. no cap. 💅

Returns:

$role — an unsigned 16-bit integer. 👑
$flags — an unsigned 8-bit integer. ✨

`parse_end_request_body`

Parses a FCGI_EndRequestBody. it's giving end-of-request realness. 🎀

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. the blueprint, the moment. ✨

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. plural, we love a good pair. 🫶

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. the whole thing, the moment. 🔥

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. same vibe, different args. 💅

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. mystery type? iconic. 🦋

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. periodt. 💅

🩺 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 📜

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

source/version: perl v5.36.0, date: 2022-11-21, page: Net::F...otocol(3pm) — mwah 💋

📦 where this page comes from

debian bookworm: libnet-fastcgi-perl 0.14-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: libnet-fastcgi-perl 0.14-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libnet-fastcgi-perl 0.14-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libnet-fastcgi-perl 0.14-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libnet-fastcgi-perl 0.14-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms